Gitlab and workflow¶
Tapenade source repository is located here: https://gitlab.inria.fr/tapenade/tapenade.
Development uses the gitflow workflow.
The master
branch stores the official release history, and the develop
branch serves as an integration branch for features.
Continuous integration and tests¶
Each pull from a git branch is verified by the automated tests on
the gitlab-ci
and Jenkins
continuous integration servers.
For master
and develop
git branches, all tests must succeed.
Cf .gitlab-ci.yml
configuration file for gitlab pipeline and
../local/README-jenkins.md
for Jenkins jobs.
Java conventions¶
We recomment no specific coding convention other than “make life easy for the person who will read your code”. If you develop a new component in Tapenade, feel free to use the convention that you feel most readable. If you just browse through an existing piece of code, please refrain from enforcing your own favorite conventions. If you need to apply just a few changes to the source, use your judgement. Please assume that the previous contributor had good reasons for their stylistic choices.
We strongly discourage using automatic reformatting tools to the source.
Convention, nomenclature on Tapenade variable names¶
“source”, “src”, should be used (rather than “orig”, “origin”) to refer to things that belong to the original, non-differentiated program.
“copy” should be used to refer to copies of the source objects that will be placed into the reverse differentiated code.
“reverse”, “rev”, should be used to refer to the reverse mode of AD, e.g. to the complete adjoint code and not only its backwards sweep.
“diff” should be used to relate to the general differentiated code, or specifically to its backward sweep if the forward sweep has a different thing for itself (ADJOINT_SPLIT_MODE). In this last case, the specific thing for the split forward sweep is referred to by “fwdDiff” instead of “diff”.
“origin”, “orig”, should be used to refer to the origin of a directed arrow, such as the “origin” of a FGArrow.
“destination”, “dest”, should be used to refer to the destination of a directed arrow, such as the “destination” of a FGArrow.
“forward”, “fwd”, should be used to refer to the forward sweep of a reverse-differentiated code.
“backward”, “bwd”, should be used to refer to the reverse sweep of a reverse-differentiated code.
“downstream”, “ds”, should be used to refer to the source execution direction that goes from entry to exit in the “source” program. In the bwd sweep, code is executed “upstream”.
“upstream”, “us”, should be used to refer to the opposite of the source execution direction that goes from exit to entry in the “source” program, and therefore goes along the execution direction of the bwd sweep.
“entry” refers to the true, final execution order of an object.
“exit” refers to the true, final execution order of an object. Therefore a Block or a sweep, regardless fwd or bwd, is always executed from entry to exit.
Comments¶
Javadoc comments in the Java source files are delimited by
the /** ... */
delimiters.
These comments are processed by
Javasphinx
to generate the API documentation and by
the Javadoc tool to generate the complete implementation documentation.
Documentation¶
README*.md files (Mardown syntax) and index.rst file (reStructuredText) are used to generate the Tapenade Developer Documentation using Sphinx documentation generator.