Contributor’s Guide¶
Installing¶
To install for development, install from source (and be sure to install the development requirements as well):
$ git clone https://github.com/ga4gh/data-object-service-schemas.git
$ cd data-object-service-schemas
$ python setup.py develop
$ pip install -r requirements.txt
Documentation¶
We use Sphinx for our documentation. You can generate an HTML build like so:
$ cd docs/
$ make html
You’ll find the built documentation in docs/build/
.
Tests¶
To run tests:
$ nosetests python/
The Travis test suite also tests for PEP8 compliance (checking for all errors except line length):
$ flake8 --select=E121,E123,E126,E226,E24,E704,W503,W504 --ignore=E501 python/
Schema architecture¶
The canonical, authoritative schema is located at openapi/data_object_service.swagger.yaml
. All schema changes
must be made to the Swagger schema, and all other specifications (e.g. SmartAPI, OpenAPI 3) are derived from it.
Building documents¶
The schemas are editable as OpenAPI 2 YAML files. To generate OpenAPI 3 descriptions install swagger2openapi and run the following:
$ swagger2openapi -y openapi/data_object_service.swagger.yaml > openapi/data_object_service.openapi.yaml
Releases¶
New versions are released when ga4gh.dos.__version__
is incremented,
a commit is tagged (either through a release or manually), and the tagged branch
builds successfully on Travis. When both conditions are met, Travis will
automatically upload
the distribution to PyPI.
If ga4gh.dos.__version__
is not incremented in a new release, the
build may appear to complete successfully, but the package will not be uploaded
to PyPI as the distribution will be interpreted as a duplicate release and thus
refused.
The process above is currently managed by david4096.
To transfer this responsibility, ownership of the PyPI package must be transferred
to a new account, and their details added to .travis.yml
as described above.
Note that this repository will not become compliant with Semantic Versioning until version 1.0 - until then, the API should be considered unstable.
Documentation is updated independently of this release cycle.
Code contributions¶
We welcome code contributions! Feel free to fork the repository and submit a pull request. Please refer to this contribution guide for guidance as to how you should submit changes.