Contributing¶

Contributing to MISCore¶

All users are welcome to contribute and suggest changes to MISCore. You’ll need to have Git (https://git-scm.com/) installed on your system. Then, follow these steps:

First, clone the repository. Either use the Git command shown below or let PyCharm do this for you (https://www.jetbrains.com/help/pycharm/set-up-a-git-repository.html#clone-repo).
```
git clone https://gitlab.com/erasmusmc-public-health/early-detection-and-screening/miscore.git
```
If you used the Git command, move into the newly created directory:
```
cd miscore
```
Install or upgrade all required Python packages using the following command.
```
python -m pip install --upgrade -r requirements.txt
```
All changes should be made on a separate branch. If this branch already exists, skip this step. Otherwise, you can create a branch using the Git command shown below or by following the instructions at https://www.jetbrains.com/help/pycharm/manage-branches.html#create-branch. Try to choose a meaningful name for the new branch.
```
git branch branch-name
```
In case your changes will solve an issue on GitLab, you can also click on the “Create merge request” button on the issue page (https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-new-branch-from-an-issue). This will automatically create a new branch and open a merge request.
Move to the newly created branch by using the following command or by following the instructions at https://www.jetbrains.com/help/pycharm/manage-branches.html#switch-branches.
```
git checkout branch-name
```
Now, you can make some changes to the code. If possible, try to split up these changes into multiple smaller, coherent changes. For each change, follow these steps:
- If you’re happy with the changes, the changed files should be added to the staging area. Probably, PyCharm already did this for you and you can skip this step. Otherwise, use the following command.
  git add file-name
- Next, commit the changes locally with a useful and concise commit message. Either follow the instructions at https://www.jetbrains.com/help/pycharm/commit-and-push-changes.html#commit or use the Git command shown below.
  git commit -m "Your commit message"
  Commit messages are important! Try to follow the rules listed here: https://chris.beams.io/posts/git-commit/.
At this point, you made the changes only locally. Push your commits to GitLab using the command shown below or follow the instructions at https://www.jetbrains.com/help/pycharm/commit-and-push-changes.html#push.
```
git push
```
Finally, submit a merge request on GitLab (https://gitlab.com/erasmusmc-public-health/early-detection-and-screening/miscore/-/merge_requests). This way you request your changes from the separate branch to be merged into the main branch. Note that a merge request has already been created if you clicked on “Create merge request” on an issue page before.

Update branches with changes from main¶

Since many people work on MISCore simultaneously and create separate merge requests, the main branch is continuously updated. To keep the branch you are working on up-to-date, it is recommended to update the branch with the changes from main regularly. To do so, you can merge the changes from main into your branch (rebasing is another option, but not recommended).

Make sure the main branch is up-to-date. In PyCharm, click on Git in the top bar and then on Branches. A pop-up window will appear with all the available branches, left-click on the main branch and select “Update”. Alternatively, go to the branch view on the bottom right of your PyCharm window.
Navigate to the branch you would like to update. Go to the branch view as before, left-click on your branch and select “Checkout”.
Merge changes of main into your current branch. Again, go to the branch view as before, left-click on the main branch (while you are in your branch) and select “Merge into current”.
If there are no merge conflicts, you have successfully updated your branch and you can push it to GitLab.
If there are merge conflicts, a pop-up window will open titled “Conflicts” which shows all files that contain merge conflicts. You can accept all changes from your branch or the main branch by clicking “Accept Yours” or “Accept Theirs”. Click on “Merge” if you want to review the conflicts and decide on a case-by-case basis.
- PyCharm provides a tool for resolving these conflicts locally. Another pop-up window will open titled “Merge Revisions for your_file.py”. This window consists of three panes:
  
  The left pane shows the read-only local copy of your branch.
  
  The right pane shows the read-only version of main.
  
  The central pane is a fully-functional editor where the results of resolving conflicts are displayed. Initially, the contents of this pane are the same as the base revision of the file, that is, the revision from which both conflicting versions are derived.
- The layout of this window gives you multiple options.
  
  On the top right you can see how many changes and conflicts are left. With the arrows on the top left you can navigate to the next (or previous) conflict.
  
  You can click on “Apply non-conflicting changes”.
  
  You can accept all changes from your branch or main branch by clicking “Accept Left” or “Accept Right” on the bottom of the window.
  
  With multiple conflicts you can also decide on a case-by-case basis.
  
  Accept the changes from your branch: Click on the two arrows on the side of the left pane (to accept) and click on the X on the side of the right pane (to ignore).
  
  Accept the changes from the main branch: Do the reverse of the first option.
  
  Accept both changes from your branch and main. First click on the two arrows on one side and then on the two arrows on the other side, PyCharm will add new lines when necessary.
- Once all conflicts have been resolved a green message box appears “All changes have been processed. Save changes and finish merging”. Click on “Apply” to apply the changes and to finalize the merge. You have successfully updated your branch and you can push it to GitLab.

For more information see the PyCharm Handbook on Resolve Git conflicts.

Approving merge requests¶

All changes to the main branch should be proposed via merge requests. Before a merge request can be accepted, all threads should be resolved and the pipeline should pass. Also, approvals from the maintainers is required. Before approving a merge request, you might want to check the following:

Are added modules, functions and classes also added to the documentation?
Are clear comments added wherever required?
Is the added/changed code consistent with other code?
Should any tests be added to the test suite?
Will these changes break any code that was compatible with the latest release? If so, can we prevent this?
Are there any typos?
Do the changes significantly decrease performance? If so, can the changes be implemented in a more efficient way?

By default, commits are squashed when a merge request is accepted. Make sure the message of the squashed commit is clear (try to follow these rules)! In some cases, it might make more sense to not squash the commits, so that you can distribute the changes over multiple commits.