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 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 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 top level 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
Starting Your Own Action¶
In OST we call scripts/ programs ‘actions’. They are started by a
launcher found in your staging directory at stage/bin/ost. This little
guy helps keeping the shell environment in the right mood to carry out your
job. So usually you will start an action by
$ stage/bin/ost --help
Starting new action do go for a dedicated branch for action-development. There you can produce intermediate commits while other branches stay clean in case you have to do some work there which needs to get public.
After preparing your repository its time to create a file for the action. That is a bit different than for modules. Assuming we are sitting in the repository’s root:
$ touch action/ost-awesome-action
$ chmod +x action/ost-awesome-action
Two things are important here: actions are prefixed with ost-, so they
are recognised by the ost launcher. Secondly, action files need to be
executable, which does not propagate if you do it after the first call to
make.
To get the new action recognised by make to be placed in
stage/libexec/openstructure, it has to be registered with cmake in
actions/CMakeLists.txt:
1 add_custom_target(actions ALL)
2
3 ost_action_init()
4 ost_action(ost-awesome-action actions)
Just add your action with its full filename with a call to ost_action at the end of the file.
Now its time to fill your action with code. Instead of reading a lot more of
explanations, it should be easy to go by examples from the actions
directory. There are only two really important points:
No shebang line (
#! /usr/bin/python) in your action! Also no#! /usr/bin/env pythonor anything like this. This may lead to funny side effects, like calling apythoninterpreter from outside a virtual environment or calling a different version. Basically it may mess up the environment your action is running in. Actions are called byost, that’s enough to get everything just right.The code of your action belongs in the
__main__branch of the script. Your action will have own function definitions, variables and all the bells and whistles. Hiding behind__main__keeps everything separated and makes things easier when it gets to debugging. So just afterimport alot def functions_specific_to_your_action(...): if __name__ == "__main__": <put together what your action should do here>
start putting your action together.