======= Code Development and Contribution ======

===== Code Repositories =====
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]]

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

==== Developing in a Fork on GitHub ====
Advantages:
  * nicely integrated into the GitHub ecosystem
  * you anyway need a fork to create a pull request later
Disadvantages:
  * everything you do is public

=== How to Create a Fork on Github ===
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".

==== Developing in a Private Repository Hosted Somewhere Else ====
Advantages:
  * private, preliminary work is not directly public
Disadvantages:
  * needs more work
  * you need a fork on GitHub to create a pull request later

=== How to Create a Private Repository ===

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:
  - Click the blue button "New project" on the upper right corner
  - Then select "Import Project" and "Repository by URL"
  - 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
  - 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.

=== How to Work with a Private Repository ===
== Configuration Steps ==
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

== Giving other People Access to your Private Repo ==
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.

== Creating a new Branch ==
A new project or feature should, if possible, be started directly from the upstream main branch:
  - git checkout main
  - git pull
  - git branch new_branch_name
  - git checkout new_branch_name

== Updating from the Upstream Repo ==
If you want to get the newest changes from the upstream repo into your current branch, you can:
  - fetch the private repository: git fetch origin
  - merge the changes into your current branch with: git merge origin/main

== Pushing to the GitHub Fork ==

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.

=== Getting Your Contribution into the Upstream Repo ===

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.

=== For Maintainers: Merging a 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.