You are reading the documentation for version 1.6 of OpenStructure. You may also want to read the documentation for: 1.1 1.2 1.3 1.4 1.5 devel
Contributing to OpenStructure¶
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 https://dng.biozentrum.unibas.ch/git/ost.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.
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 summarizes 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 so that they can safely ignore the e-mail.
Additionally, they also come in handy when using the –online option of
OpenStructure uses sphinx as the documentation generator. The main part of the documentation of each module resides in files with the
From the top level directory of the git repository convert the .rst files to html by using the doc/make.py script :
The script first recursively searches for modified
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
.. 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
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
# this takes all the changes you introduced and writes them to # changeset.diff git format-patch --stdout develop > changeset.diff
If you got a patch from someone else and would like to use apply it to your repository, use
git am < changeset.diff
Enter search terms or a module, class or function name.
You are here