/technical-reference

This Technical Reference is a collection of basic guidelines and references for development and maintenance of infrastructure services under development by CESSDA, CLARIN & DARIAH.

Primary LanguagePythonCreative Commons Attribution 4.0 InternationalCC-BY-4.0

Technical Reference

Documentation Status

This is the common Technical Reference developed by the EURISE Network, a cooperation of CESSDA ERIC, CLARIN ERIC and DARIAH ERIC.

The Technical Reference is available online and intended to form a set of basic guidelines and references to inform development and maintenance of infrastructure services for the participating infrastructures and beyond.

This reference's particular purpose

The EURISE Network Technical Reference, is a collection of guidelines and how-tos, mainly aimed at developers contributing to the participating infrastructures. It serves as a combined introduction to many aspects of software engineering, while being neutral with respect to particular choices. This ensures the largest possible intersection of recommendations, while allowing the partners to implement their own lightweight specifications on top. This purpose sets it apart from many similar guides.

In creating the documents, existing work from the community has been taken into account. In particular, work carried out by CLARIAH-NL as well as the Netherlands eScience Center and the UK Software Sustainability Institute have been used, heavily relying on the Netherlands eScience Center Guide and the CLARIAH Software Quality Guidelines.

Working with the TR

The documents are compiled with Sphinx and automatically published on Read the Docs on commit. Specific releases are available on Read the Docs to be used for implementations.

To work locally, install everything to an venv

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Compile with

make clean
make html
make latexpdf

Releases

  1. To release a new version, make sure all changes are commited to master.
  2. Switch to a new branch for the version
  3. Reflect the version in conf.py, both as version and release`.
  4. Make a release commit.
  5. Tag the commit with a release tag
  6. In the master branch, update conf.py for the next iteration.
  7. Commit the new cycle to master

Development

The Technical Reference is still in early development and maintained by volunteers from the infrastructures involved. Contributions are welcome, see CONTRIBUTING.md, contributors are listed in AUTHORS.md.

This work was originally started as part of the “DESIR – DARIAH ERIC Sustainability Refined” project for DARIAH, receiving funding from the European Commission under grant agreement 731081 and has been transferred to the EURISE Network for future maintenance.