Code organization and release process

Directories

• atlas: atlas entries with character tables

• docs: compiled documentation ready for a web browser

• external: external libraries, either included as a Git submodule (if available on a public repository such as Github), or vendored (like vpi). Here is the procedure to update a git submodule named project:

  1. Enter the submodule directory with cd external/project

  2. Pull the latest version of the project with git pull origin master

  3. Go back to the external folder with cd .. and update the commit number in the file submodules.ini so that it matches the new status of the submodule (this is needed for the autoinstall feature).

  4. Commit these changes in the main RepLAB repository: git add project submodules.ini, git commit -m "submodule project updated"

• generated: files auto-generated by replab_generate and replab_sphinx

• sphinx: source files for the executable documentation

• src/+replab: the main RepLAB package, containing the main classes/methods

• src/+replab/+subpackages: implementation files for different submodules, or experimental stuff

• tests: tests written using MOxUnit, augmented with our laws test framework, doctests and notebooks. Tests in this folder can be launched with replab_runtests. Dedicated Github actions launch test suites on new commits and pull requests.

The release process

RepLAB has a major.minor.patch version number.

The develop branch contains a snapshot, i.e. a version number that ends in -SNAP.

The master branch contains a release, i.e. a version number that does not end in -SNAP.

The gh-pages contains the documentation pages.

See replab_release for a description of the release process.

Website release process

The online documentation is generated by the replab_sphinx function with the doublePass option. This creates a full copy of the website in the docs folder. For more details on how to set up a local Sphinx workflow, see Sphinx tips and tricks.

The release of the RepLAB main website is automatized and can be triggered with a dedicated Github action. An annex repository allows to test a new website online without affecting the current one.