Contributing to OpenStructure¶
Note
This document describes how to develop features to be included in OpenStructure. If you are mainly planning to use the framework, from Python you probably shouldn’t read this document and refer to the API docs instead.
OpenStructure uses git as the revision control system. It allows for branch-and-merge driven workflows ideal for a scientific environment.
The main repository can be browsed here.
Even though, technically, there is no such a thing as a central repository in git, we use a central “repository of truth” where everyone is pulling from. You can get the source code with git clone:
git clone https://git.scicore.unibas.ch/schwede/openstructure.git
For information on how to install OpenStructure from source, refer to Installing OpenStructure From Source.
Leaving aside all the short-lived features branches, the OpenStructure repository has two long-lived branches, one called master and one called develop. Master contains the latest stable changes, develop contains features currently under development that are potentially not working. Once stable, the changes in develop will be merged into master and together will form the next release. A very detailed description of the branching model used for OpenStructure is available at this site.
Making Changes¶
The common workflow of making changes to OpenStructure is depicted in the following section.
Even though it is not neccessary, it is advised to carry out your changes in a separate branch. The new branch can be created with:
# checkout branch my_branch and create it if it doesn't exist yet.
# Of course you are free to name the branch whatever you want.
git checkout -b my_branch
From now on, all your work will be carried out in my_branch. Make your changes and once you are happy, commit them to your repository.
Writing Good Commit Messages¶
Your commit message should have a one-line description that summarize the change and optionally a more detailed description of what the changes imply. An example from the commit history.
improve warning when using generic property of string type in query
Fixes BZDNG-204
The one-liner and the detailed description are separated by an empty line. The reason for this format is that the one-line description will be used as the subject line for the patches generated by format-patch and the ones sent to the commit mailing lists. People can quickly see if the change is of interest to that they can savely ignore the e-mail.
Additionally, they also come in handy when using the –online option of git log.
Writing Documentation¶
OpenStructure uses sphinx as the documentation generator. The main part of the documentation of each module resides in files with the .rst extension (a markup language called reStructuredText) in a sub-folder called doc.
From the toplevel directory of the git repository convert the .rst files to html by using the doc/make.py script :
ost doc/make.py
The script first recursively searches for modified .rst files, starting at the modules directory and copies the files that have changed to doc/source. It also copies images to the source directory. Then it runs sphinx to convert the documentation to html. If no further options are given to the script, the html documentation is generated. The HTML, CSS and static media files will be put into doc/build/html.
For classes and functions written in Python, it is possible to tell sphinx to extract the documentation directly from the doc-string. For example, to get the documentation for LoadPDB(), you can use:
.. autofunction:: ost.io.LoadPDB
Synchronizing with upstream changes¶
In the meanwhile, someone else might have committed changes to the develop branch. The best and cleanest way to incorporate these changes is to rebase your changes onto the latest develop branch:
git checkout develop
# pull the latest changes to make sure we are up to date
git pull
git checkout my_branch
# rebase the changes
git rebase develop
Sending Patches¶
Changes always go into develop first before being integrated into master. Unless, you have commit access, the easiest way to share your changes is to create a patch and send it by email to the mailing list or one of the developers. To create a suitable diff, rebase your changes onto the latest develop branch and use the format-patch command:
# this takes all the changes you introduced and writes them to
# changeset.diff
git format-patch --stdout develop > changeset.diff
Applying Patches¶
If you got a patch from someone else and would like to use apply it to your repository, use git am.
git am < changeset.diff