BOLTS consists of quite a lot of code and data and to manage this code and data and the changes made to it, git is used. Git is a distributed version control system and this allows everybody who wants to work with git to obtain a version of BOLTS (called a fork), that is separate from the main version, so that it is possible to play around, add parts and develop new features without breaking the master branch. git then makes it very easy to move the changes made in one branch to the master branch.
There exist many different workflows and ways how to develop software with git. I will present three different ways that I consider useful for the purpose of contributing to BOLTS. For more information see the git documentation or the GitHub documentation.
For this way you need a GitHub account. It is probably the easiest way to make small corrections and additions, and works well for all tasks that involve editing and creating text files.
Go to the BOLTS repository page, there you see a list of all files and directories and you can navigate around by clicking on them.
To edit a file just click on it, and then use the Edit button to open the web
based editor. You can now make your changes. When you are done, scroll to the
bottom of the page and add a short description, and a longer explanation about
what you changed if necessary. Try to use precise language and avoid having
unrelated changes in one commit (like fixing a typo and adding a new class).
Alternatively you can add a new file by clicking on the small + next to the
repository name. A editor page opens, and you can give a filename and start
typing contents.
Finally hit the Commit Changes button at the bottom of the page. GitHub will
now automatically fork the BOLTS and create a new commit with the changes you
just made.
On the next page you are asked whether you want to offer your changes to the BOLTS maintainer, this is called a pull request. If your changes are more substantial, you should add a short explanation, why you think these changes should go into the main branch. You can then send the pull request.
The maintainer can now look at your changes, decide whether he wants them in the main branch, give you feedback and ask for further modifications.
For this way you also need a GitHub account. It allows you also to work offline. This way requires you to work with the commandline.
This way will also create a fork of BOLTS on the GitHub server, but additionally you will also obtain a fork on your own computer. You make changes to the one on your own computer and then communicate these changes back to the GitHub fork. This way you can work offline, you only need to be online to push your changes.
Before you start you should install and set up git supplying it with your name and email address, so that your contributions can be attributed to you.
There is a pretty good tutorial how to fork a repository on the GitHub help pages, where you can also find more information about working with git and GitHub.
The next steps are explained in the section about Creating topic branches and
committing your work.
For this way you do not need a GitHub account, and it allows you to work offline. In contrast to working with a GitHub fork, your proposed changes are not published online, but sent to the maintainer by email.
Before you start you should install and set up git supplying it with your name and email address, so that your contributions can be attributed to you.
To obtain a local version of the BOLTS git repository fire up the commandline, change to the directory where you want to store the BOLTS repository and type
git clone git@github.com:jreinhardt/BOLTS.git
a new directory named BOLTS will be created that contains the current
development state.
The next steps are explained in the section about Creating topic branches and
committing your work.
You now should have a local copy of BOLTS. Before you start making changes, you should create a new branch. There is a quite detailed description about branches on the git-scm website. In short, a branch is like a parallel universe of the source code. This allows you to work on independent changes (like adding a new collection and writing base modules for another one) in parallel, by storing them in separate branches. But if you do not want to work in parallel, it boils down to a few commands that you use before and after you did your changes.
To create a new branch type on the commandline
git checkout -b "branchname"
and replace branchname by a short descriptive name like "steppermotorcollection", if you want to add a new collection for stepper motors or "hexsocketbases" if you want to add base geometries for the hexsocket collection. A branch that is used to work on a certain feature is called a topic branch.
If you now type
git status
it tells you which branch you are on
# On branch steppermotorcollection
...
To switch branches you can use
git checkout branchname
Before you edit files, make sure you are in your topic branch. To record a set of changes, you first "add" the changed or new files that you want to include in the commit by
git add filename
git add filename2
git add filename3 filename4
with
git status
you can get a list of changed files that will be committed and those that will not be committed. Finally, to commit the added changes use
git commit
A editor opens and you can enter a description of the changes. The first line is a short description. If the changes deserve a more detailes explanation, one can be added after a empty line.
Usually one structures the work on one feature into a series of commits that do simple changes each. A rule of thumb is: If you cannot precisely describe the changes in one line, you should consider to split it into smaller commits.
If you have finished the work on your feature you submit the changes either by fire off a pull request, or by creating a bundle and send it by mail to the maintainer.
To push your topic branch to GitHub, you use
git checkout branchname
git push -u origin branchname
This creates a new branch called branchname on your BOLTS fork on GitHub. If you make more changes on this topic branch (maybe on request of the maintainer), you can use just
git push origin branchname
The initiation of a pull request on GitHub is covered very well by this tutorial.
Another possibility to contribute your changes is to create a bundle file containing all the commits you added.
To create the bundle use
git bundle create branchname.bundle origin/master..branchname
but replace branchname by the name of your branch.
The resulting file can be attached to an email with a description what this does and then send it to BOLTS@ist-dein-freund.de.