diff --git a/modules/doc/contributing.rst b/modules/doc/contributing.rst new file mode 100644 index 0000000000000000000000000000000000000000..6338ff5c467310e8e83098b1fc358b3d3f7a2582 --- /dev/null +++ b/modules/doc/contributing.rst @@ -0,0 +1,74 @@ +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 :doc:`API docs <index>` instead. + +OpenStructure uses `git <http://git-scm.org>`_ 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 <http://dng.biozentrum.unibas.ch/git/>`_. + + +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``: + +.. code-block:: bash + + git clone https:/dng.biozentrum.unibas.ch/git/ost.git + + +For information on how to install OpenStructure from source, refer to :doc:`install`. + +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 <http://nvie.com/posts/a-successful-git-branching-model/>`_. + + + +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: + +.. code-block:: bash + + # 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. + +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: + +.. code-block:: bash + + 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: + +.. code-block:: bash + + # 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``. + +.. code-block:: bash + + git am < changeset.diff \ No newline at end of file diff --git a/modules/doc/install.rst b/modules/doc/install.rst index abd0b2b88fc0b8a8847d45fecad463bda6219b5c..525561543c3cb201d7ff8ed417a7fd86041a3fa0 100644 --- a/modules/doc/install.rst +++ b/modules/doc/install.rst @@ -7,6 +7,7 @@ Installing OpenStructure From Source mainly insterested in using OpenStructure and are not planning to modify the code of OpenStructure itself, please use one of the binaries `available for download <http://www.openstructure.org/download/>`_. + Brief Overview -------------------------------------------------------------------------------- @@ -14,7 +15,7 @@ Brief Overview Compiling OpenStructure consists of several steps that are described below in more detail. In essence, these steps are: * Installing the Dependencies - * Checking out the source code from SVN + * Checking out the source code from GIT * Configuring the build with cmake * Compiling an Linking @@ -54,20 +55,20 @@ Solutions->VC++ directories. Choose 'bin' directories to enter program paths to cmake, qmake and python, 'lib' directories to point to the location(s) of your dependencies. -Checking out the Source + + +Getting the Source Code -------------------------------------------------------------------------------- -You can checkout the source from SVN. The repository is located at - https://dng.biozentrum.unibas.ch/svn/openstructure/trunk +OpenStructure uses `git` as the revision control system. The main repository can be browsed `here <http://dng.biozentrum.unibas.ch/git/>`_. To get the source code, use git clone: -If you are using the commandline client, type in your shell .. code-block:: bash - svn co https://dng.biozentrum.unibas.ch/svn/openstructure/trunk - -On Windows, we recommend to install a graphical frontend for svn, for example `tortoisesvn <http://tortoisesvn.tigris.org>`_. + git clone https://dng.biozentrum.unibas.ch/git/ost.git <directory-name> + +The above command will clone OpenStructre into the directory called `directory-name`. If omitted, the directory will be called ost. Alternatively, you might consider getting one of the nightly source code snapshots from the `downloads section <http://www.openstructure.org/downloads/>`_. Configuring diff --git a/modules/index.rst b/modules/index.rst index 147274735b6617024bf345b5d88c6ce4b031c8fa..a23c7ecb2ef11618aac5cc099a8545451052f51d 100644 --- a/modules/index.rst +++ b/modules/index.rst @@ -21,6 +21,7 @@ OpenStructure documentation gui/gui newmodule external + contributing For Starters -------------------------------------------------------------------------------- @@ -85,7 +86,7 @@ Graphical User Interface Extending OpenStructure -------------------------------------------------------------------------------- -**Howto:** :doc:`write new modules <newmodule>` | :doc:`integrate third-party tools <external>` | :doc:`logging <base/logging>` +**Howto:** :doc:`write new modules <newmodule>` | :doc:`integrate third-party tools <external>` | :doc:`logging <base/logging>` | :doc:`instructions for developers <contributing>`