Code Development and Contribution

The development of the CP-PAW code is organized via GitHub. The main repository there is https://github.com/cp-paw/cp-paw and the upstream branch is the main branch. Changes in this branch are only allowed via pull requests. Everything below assumes that you have a GitHub account. If not, the first step is to get one: https://github.com/join

You can either develop your contribution to the CP-PAW code in a fork on GitHub or in a private repository hosted somewhere else:

Advantages:

• nicely integrated into the GitHub ecosystem
• you anyway need a fork to create a pull request later

Disadvantages:

• everything you do is public

Go to https://github.com/cp-paw/cp-paw and click the button “Fork” on the top right. Now you can push commits and branches to this repo however you like. If some work is finished and should go into the upstream repo, please follow the steps further down on “Getting Your Contribution into the Upstream Repo”.

Advantages:

• private, preliminary work is not directly public

Disadvantages:

• needs more work
• you need a fork on GitHub to create a pull request later

We will only cover the case of creating a private repository in Gitlab. Other services work similarly. The Repository will be configured so that the main branch is always synchronized with the main branch from the upstream CP-PAW repo on Github. When logged in at your Gitlab service:

1. Click the blue button “New project” on the upper right corner
2. Then select “Import Project” and “Repository by URL”
3. Fill out with:
   • Git repository URL: https://github.com/cp-paw/cp-paw
   • Enable “Mirror repository”
   • Project Name: CP-PAW (or something else)
   • Project URL: enter your username to put the private repo in your private namespace
4. Click to create.

You will be forwarded to your private repository, and on top it will say “Mirrored from https://github.com/cp-paw/cp-paw.”

That means that the main branch of this repository is always the same as in the upstream repository. Remember not to change the main branch of this repo actively.

After cloning your private repository, you need to create an origin for your fork on Github. This is necessary to push branches from your private repository to the fork to create pull request for the upstream repo.

You can do this with:

git remote add github [URI of your fork on github]

The URI can either be the https-address or the ssh-address, but we recommend the ssh-address.

Then fetch the current state with:

git fetch github

In Gitlab, on the main page of your private repository, go to “Project Information” on the left, then “Members”, then “Invite members” on the top right. Here you can search for people and select their role. We recommend the role of guest. As guests, they can't modify your repository. Please note that in Gitlab, users first have to be logged in once to be found in the search.

A new project or feature should, if possible, be started directly from the upstream main branch:

1. git checkout main
2. git pull
3. git branch new_branch_name
4. git checkout new_branch_name

If you want to get the newest changes from the upstream repo into your current branch, you can:

1. fetch the private repository: git fetch origin
2. merge the changes into your current branch with: git merge origin/main

To be able to create a pull request, your work first has to be publically available in your GitHub fork repo. Assuming that you have a branch named “new_work” with the changes/contribution you want to bring into the upstream repo, push it to your fork repo with:

git push github new_work

Then follow at steps in the following section to create a pull request.

If you push a branch to your fork repo at Github, you will be prompted directly with the message

remote: Create a pull request for 'new_work' on GitHub by visiting: remote: https://github.com/robertschade/cp-paw/pull/new/new_work

You can use the given URL to create a pull request from this branch to the main branch of the blessed repo. If you want to add changes, you simply commit it to the branch and push the branch again. They are automatically included in the pull request.

When visiting https://github.com/cp-paw/cp-paw/pulls, you will see the list of open pull requests, review them, request changes or feedback from the author, and finally, merge them.

Technically there are three possibilities for how to integrate a contribution into the upstream repo:

• Merge with a merge commit: Merging with a merge commit is the most straightforward as it conserves the history of the commits. It preserves compatibility with other repositories where commits from the pull request might already be included. However, it creates an additional merge commit.
• Squash and merge: The commits from the branch are combined into one commit and added to the upstream repo. There is no relation between the combined/squashed commit and the original set of commits which breaks compatibility.
• Rebase and merge: The commits from the branch are committed on top of the current state of the upstream branch. Since the rebased commits have a different history than the original commits, they are not compatible with the repository they came from and this compatibility is broken.

For the CP-PAW development, we have decided only to allow “Merge with a merge commit” because preserving the compatibility doesn't break established development workflows.