Table of Contents

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:

Disadvantages:

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:

Disadvantages:

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:

  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:
    • 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.

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:

  1. git checkout main
  2. git pull
  3. git branch new_branch_name
  4. 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:

  1. fetch the private repository: git fetch origin
  2. 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:

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.