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 python or anything like this. This may lead to funny side effects, like calling a python interpreter 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 by ost, 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 after

    import alot
    
    def functions_specific_to_your_action(...):
    
    if __name__ == "__main__":
        <put together what your action should do here>
    

    start putting your action together.

Search

Enter search terms or a module, class or function name.

Contents

Documentation is available for the following OpenStructure versions:

(Currently viewing dev) / 2.8 / 2.7 / 2.6 / 2.5 / 2.4 / 2.3.1 / 2.3 / 2.2 / 2.1 / 2.0 / 1.9 / 1.8 / 1.7.1 / 1.7 / 1.6 / 1.5 / 1.4 / 1.3 / 1.2 / 1.11 / 1.10 / 1.1

This documentation is still under heavy development!
If something is missing or if you need the C++ API description in doxygen style, check our old documentation for further information.