This section contains information for developers of Pelita.
|v0.1.1 – 2012-05-23:|
|v0.1.0 – 2011-09-21:|
The official Git-Repository is hosted at Github: https://github.com/ASPP/pelita
You can create a clone with:
$ git clone git://github.com/ASPP/pelita.git
Or alternatively via https:
$ git clone https://github.com/ASPP/pelita.git
We used to use the gitflow model, but it was too complicated. Now we just have a few simple guidelines.
The master branch is used for integration. Trivial commits such as typo fixes etc. can be committed directly to master. Anything else should be done in a feature branch using, for example, the prefix feature/. If you have commit-access to the ASPP repository, you may still want some code-review. In this case, please push the branch to your fork and issue a pull-request. If you don’t have commit-access you will have to issue a pull-request anyway. Of course, you are free to do whatever you like (rebase, filter-branch) in your own fork. We are, after all, consenting adults, but please don’t rewrite history in the ASPP repository.
If you need to read up on pull-requests, please see:
Commits should be marked. Declare both functionality and area.
|BF or FIX:||bug fix|
|ENH:||enhancement of an existing feature/facility|
|BK:||breaks something and/or tests fail|
|FO:||code formatting (adding spaces etc.)|
|PL:||making pylint happier|
|GIT:||repository mods, e.g. .gitconfig .gitattributes|
DOC/ENH: add initial README.md
This means that the content generated by Sphinx is kept in a separate branch in the source code repository called gh-pages (gh-pages branch for Pelita). This branch has its own root commit and is hence disconnected from the commits that track the project code as well as the documentation source code.
When this branch is pushed to GitHub the contained documentation is automatically deployed to the web server. There are two ways to make commits to the gh-pages branch: using a script or through a series of git command lines. Initially we used the manual commands, and then these were then converted into a script. Unfortunately, the script was subsequently upgraded multiple times and hence the manual commands and the script are completely out of sync. As a consequence, the command listing is only provided as a reference and all website updates should be performed using the script.
Use the commit-tree-doc.sh script. This will automatically make the commit of the latest version of the documentation on the gh-pages branch. After checking that everything is in order you still need to push that branch.
Run the script:
$ ./commit-doc-tree.sh Generating doc from v0.1.0-rc1-165-g3d353c9 ... Build finished. The HTML pages are in build/html. Switched to branch 'gh-pages' Your branch is ahead of 'origin/gh-pages' by 1 commit. ce78099 DOC: Sphinx generated doc from v0.1.0-rc1-165-g3d353c9
Examine the output closely and if all went well:
$ git push
And get back to work:
$ git co -
Move to the doc directory:
$ cd doc
Edit the documentation:
$ vim source/<file>.rst
$ make html
Switch to the documentation branch:
$ git checkout gh-pages
Move back up to the root directory:
$ cd ..
Copy the generate documentation here:
$ cp -r doc/build/html/* .
Add all tracked files that have been changed:
$ git add -u
Add possibly new files:
$ git add <new pages>.html
Make a commit message where XXXXXXX is the SHA-1 prefix of the commit the documentation was # generated from:
$ git commit -m "sphinx generated doc from XXXXXXX"
We used an agile project wall to track tasks for the initial stages of the development. In our case we split it into four distinct sections: todo (upper right), current iteration (upper left), done (lower left) and nice to have (lower right). Since we only had one whiteboard we kept the center for sketches and doodles. You can read about the agile project wall in the book: The Agile Samurai by Jonathan Rasmusson
Here are some photos: