diff --git a/docs/development.rst b/docs/development.rst index fb643b040..eaac9e047 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -87,6 +87,40 @@ using: $ virtualenv ga4gh-server-env $ source ga4gh-server-env/bin/activate +***************************** +Using Development Constraints +***************************** + +The server uses the GA4GH schemas as a basis for serializing and deserializing +data. This means that the server depends on the schemas, and at times a developer +will need to point at a specific version of the schemas to reflect a change to +the data model. + +There is a :code:`constraints.txt` file in the root of the source tree that can be +used to pin specific dependencies for a given requirement. For example, to use +a specific branch of the schemas when developing the server hosted by github we can add +the line: + +.. code-block:: bash + + git+git://github.com/david4096/schemas.git@protobuf31#egg=ga4gh_schemas + +This informs the installer to resolve dependencies from github before PyPi, +allowing the developer to work against a specific version of the schemas under +their control. + +By explicitly stating a dependency, others can review changes to the data model. When +a change has been accepted in the schemas, you can adjust your constraints to point +at the current master branch of schemas. + +.. code-block:: bash + + git+git://github.com/ga4gh/schemas.git@master#egg=ga4gh_schemas + + +At the time of a release, the same process allows us to specify a precise released +version of the schemas and client to develop against. + *************** GitHub workflow *************** @@ -334,22 +368,6 @@ functionality is split between the ``client``, ``server``, ``protocol`` and ``cli`` modules. The ``cli`` module contains the definitions for the ``ga4gh_client`` and ``ga4gh_server`` programs. -An important file in the project is ``ga4gh/_protocol_definitions.py``. -This file defines the classes for the GA4GH protocol. -The file is generated using the ``scripts/process_schemas.py`` script, -which takes input data from the -`GA4GH schemas repo `_. -To generate a new ``_protocol_definitions.py`` file, use - -.. code-block:: bash - - $ python scripts/process_schemas.py desiredVersion path/to/schemas - -Where ``desiredVersion`` is the version that will be written to the -``_protocol_definitions.py`` file. This version must be in the form -``major.minor.revision`` where major, minor and revision can be any -alphanumeric string. - .. _git-appendix: *********************