How to Participate as a Developer¶
- In a Nutshell
- How to Fork From Us
- Keep Track of Updates
- Pull Requests or Being Social
- Maintainer Notes
Code - Version Control¶
If you are familiar with git, feel free to jump to our github workflow section.
sudo apt-get install git
- make sure
git --versionis at least at version 1.7.10
Optional one of these. There are nice GUI tools available to get an overview on your repository.
gitk git-gui qgit gitg
- see here
Configure your global git settings:
git config --global user.name NAME
git config --global user.email EMAIL@EXAMPLE.com
git config --global color.ui "auto"(if you like colors)
git config --global pack.threads "0"(improved performance for multi cores)
You may even improve your level of awesomeness by:
git config --global alias.pr "pull --rebase"(see how to avoide merge commits)
git config --global alias.pm "pull --rebase mainline"(to sync with the mainline by
git pm dev)
git config --global alias.st "status -sb"(short status version)
git config --global alias.l "log --oneline --graph --decorate --first-parent"(single branch history)
git config --global alias.la "log --oneline --graph --decorate --all"(full branch history)
git config --global rerere.enable 1(see git rerere)
git config --get-regexp alias(show all aliases)
git config --global --unset alias.<Name>(unset alias
Git is a distributed version control system. It helps you to keep your software development work organized, because it keeps track of changes in your project. It also helps to come along in teams, crunching on the same project. Examples:
- Arrr, dare you other guys! Why did you change my precious main.cpp, too!?
- Who introduced that awesome block of code? I would like to pay for a beer as a reward.
- Everything is wrong now, why did this happen and when?
- What parts of the code changed since I went on vacation (to a conference, phd seminar, mate fridge, ...)?
If version control is totally new to you (that’s good, because you are not spoiled) - please refer to a beginners guide first.
Since git is distributed, no one really needs a server or services like github.com to use git. Actually, there are even very good reasons why one should use git even for local data, e.g. a master thesis (or your collection of ascii art dwarf hamster pictures).
Btw, fun fact warning: Linus Torvalds, yes the nice guy with the pinguin stuff and all that, developed git to maintain the Linux kernel. So that’s cool, by definition.
A nice overview about the humongous number of tutorials can be found at stackoverflow.com ... but we may like to start with a git cheat sheet (is there anyone out there who knows more than 1% of all git commands available?)
- git-tower.com (print the 1st page)
- github.com - “cheat git” gem (a cheat sheet for the console)
- kernel.org Everyday GIT with 20 commands or so
- an other interactive, huge cheat sheet (nice overview about stash - workspace - index - local/remote repositories)
If you like, you can credit someone else for your next commit with:
git commit --author "John Doe <email@example.com>"
git for svn users¶
If you already used version control systems before, you may enjoy the git for svn users crash course.
Anyway, please keep in mind to use git not like a centralized version control system (e.g. not like svn). Imagine git as your own private svn server waiting for your commits. For example Github.com is only one out of many sources for updates. (But of course, we agree to share our finished, new features there.)
Welcome to github! We will try to explain our coordination strategy (I am out of here!) and our development workflow in this section.
In a Nutshell¶
Create a GitHub account and prepare your basic git config.
Prepare your forked copy of our repository:
- fork picongpu on GitHub
git clone firstname.lastname@example.org:<YourUserName>/picongpu.git(create local copy)
git remote add mainline email@example.com:ComputationalRadiationPhysics/picongpu.git(add our main repository for updates)
git checkout dev(switch to our, its now your, dev branch to start from)
Start a topic/feature branch:
git checkout -b <newFeatureName>(start a new branch from dev and check it out)
- hack hack
git add <yourChangedFiles>(add changed and new files to index)
git commit(commit your changes to your local repository)
git pull --rebase mainline dev(update with our remote dev updates and avoid a merge commit)
Optional, clean up your feature branch. That can be dangerous:
git pull(if you pushed your branch already to your public repository)
git pull --rebase mainline dev(apply the mainline updates to your feature branch)
git log ..mainline/dev,
git log --oneline --graph --decorate --all(check for related commits and ugly merge commits)
git rebase mainline/dev(re-apply your changes after a fresh update to the
mainline/dev, see here)
git rebase -i mainline/dev(squash related commits to reduce the complexity of the features history during a pull request)
Publish your feature and start a pull request:
git push -u origin <newFeatureName>(push your local branch to your github profile)
- Go to your GitHub page and open a pull request, e.g. by clicking on compare & review
ComputationalRadiationPhysics:devinstead of the default
- Add additional updates (if requested to do so) by
push-ing to your branch again. This will update the pull request.
How to fork from us¶
To keep our development fast and conflict free, we recomment you to fork our repository and start your work from our dev (development) branch in your private repository. Simply click the Fork button above to do so.
git remote add mainline https://github.com/ComputationalRadiationPhysics/picongpu.git
git checkout dev(go to branch dev)
Well done so far! Just start developing. Just like this? No! As always in git,
start a new branch with
git checkout -b topic-<yourFeatureName> and apply your
Keep track of updates¶
We consider it a best practice not to modify neither your master nor your
dev branch at all. Instead you can use it to
pull --ff-only new updates from
the original repository. Take care to switch to dev by
git checkout dev to start
new feature branches from dev.
So, if you like to do so, you can even
of the original dev branch that way. Just start your new branch with
git branch --track <yourFeatureName> mainline/dev
instead. This allows you to immediatly pull or fetch from our dev and
avoids typing (during
git pull --rebase). Nevertheless, if you like to
your forked (==
origin) repository, you have to say e.g.
git push origin <branchName> explicitly.
You should add updates from the original repository on a regular basis or at least when you finished your feature.
- commit your local changes in your feature branch:
Now you could do a normal merge of the latest
mainline/dev changes into
your feature branch. That is indeed possible, but will create an ugly
Instead try to first update the point where you branched from and apply
your changes again. That is called a rebase and is indeed less harmful as
reading the sentence before:
git checkout <yourFeatureName>
git pull --rebase mainline dev(in case of an emergency, hit
git rebase --abort)
Now solve your conflicts, if there are any, and you got it! Well done!
- do not push to the main repository on a regular basis, use pull request for your features like everyone else
- never do a rebase on the mainline repositories (this causes heavy problems for everyone who pulls them)
- on the other hand try to use pull –rebase to avoid merge commits (in your local/topic branches only)
- do not vote on your own pull requests, wait for the other maintainers
- we try to follow the strategy of a-successful-git-branching-model
Last but not least, help.github.com has a very nice FAQ section.
More best practices.
Test Suite Examples¶
You know a useful setting to validate our provided methods? Tell us about it or add it to our test sets in the examples/ folder!