Workflow to submit code changes
*********************************
Preliminaries
=============
While our project PyRPL is yet too small to make it necessary to define
collaboration guidelines, we will just stick to the guidelines of the
`Collective Code Construction Contract
(C4) `__. In addition, if you would
like to make a contribution to PyRPL, please do so by issuing a
pull-request that we will merge. Your pull-request should pass
unit-tests and be in PEP-8 style.
Use git to collaborate on code
==============================
As soon as you are able to, please use the git command line instead of
programs such as gitHub, since their functionality is less accurate than
the command line's.
1. Never work on the master branch. That way, you cannot compromise by
mistake the functionality of the code that other people are using.
2. If you are developing a new function or the like, it is best to
create your own branch. As soon as your development is fully
functional and passes all unit tests, you can issue a pull request to
master (or another branch if you prefer). Add a comment about the
future of that branch, i.e. whether it can be deleted or whether you
plan to work on the same branch to implement more changes. Even after
the pull request has been merged into master, you may keep working on
the branch.
3. It often occurs that two or more people end up working on the same
branch. When you fetch the updates of other developers into your
local (already altered) version of the branch with :code:`git pull` you
will frequenctly encounter conflicts. These are mostly easy to
resolve. However, they will lead to an ugly history. This situation,
along with the standard issue, is well described `on
stackoverflow `__.
There are two ways to deal with this:
1. If you have only minor changes that can be summarized in one
commit, you will be aware of this when you type::
git fetch
git status
and you are shown that you are one or more commits
behind the remote branch while only one or two local files are
change. You should deal with this situation as follows::
git stash
git pull
git stash pop
This way, your local changes are saved onto the 'stash', then you
update your local repository with the remote version that includes
other developers' changes, and then you pop the stash onto that
altered repository. The result is that only your own changes and the
way you resolved the conflict will appear in the git history.
2. If you have a considerable amount of changes, we can accept the
ugly merge commits. Just stay with :code:`git pull` and put the
keyword 'merge' into the commit message. To understand what is
going on, read the copy-paste from the above link (copy-paste
follows):
For example, two people are working on the same branch. The branch
starts as::
...->C1
The first person finishes their work and pushes to the branch::
...->C1->C2
The second person finishes their work and wants to push, but can't because they need to update.
The local repository for the second person looks like::
...->C1->C3
If the pull is set to merge, the second persons
repository will look like::
...->C1->C3->M1
\
->C2->
It will appear in the merge commit that the second person has
committed all the changes from C2. Nevertheless, C2 remains in the
git history and is not completely lost. This way, the merge commit
accuratly represents the history of the branch. It just somehow spams
you with information, so you should always use the former option 3.i
when you can.