Contribute to the code

Editor

The use of VSCode is strongly recommended. Please check that you have installed and enabled at least the following plugins:

• Angular language service
• Angular template formatter con “close tag same line” impostato
• Beautify css/sass/scss/less
• Npm
• Npm intellisense
• TSLint

Programming style

The code written by each developer must be clear, well formatted and above all well commented, in such a way as to explain its function to those who will have to hand over that specific portion of code. Comments, such as log messages on GitHub and any documentation accompanying the code itself, must be in English.

Since most of the processing is based on handling the TEI/XML elements used for semantic annotation, you will have to include all TEI-related use cases in the edition.xml sample document, so that it will be possible to have a comprehensive collection of examples to test the new code. When the edition.xml document will be complete (please remember to add comments to signal the start of your TEI sample code), and you feel ready to submit a PR, you must create a sub-directory with the same name of the branch you are working on within the https://github.com/evt-project/evt-sample-documents/blob/master/EVT3/pr-testing-files directory, and copy the edition.xml document in it, so that it can be used to test the PR at runtime. Also see the Sample documents section.

Commit Messages

For commit messages each developer must follow the guidelines described on https://chris.beams.io/posts/git-commit/. This style of commit message has several advantages and helps keep the repository history clean.

Commit messages that do not follow the chosen style will be rejected (rebase is your friend to rename commits). This limits or completely excludes (based on how strictly the guidelines apply) the presence of insignificant commits such as "commit to branch", "I recovered my pc, I commit to checkout".

Branching strategy

Git-flow is used as branching strategy (https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow, https://danielkummer.github.io/git-flow-cheatsheet/)

This strategy has significant advantages:

• it keeps the history of the repository clean and readable, facilitating the identification of points where bugs appear or the rollback to previous versions;
• the history of the release versions is immediately identifiable;
• it makes the addition of new features and bug fixes systematic.

Merge strategy

Merging of a branch to master and develop is prevented. The merge on develop is managed through the pull request mechanism.

The strategy of merge on master should be done only at the time of a new release and only by the managers of the pull request merge.

This mechanism allows to check what goes into develop and to do a minimum of code review (code quality control). This increases the stability of the software, decreases the presence of bugs and increases the overall knowledge of the code by the entire development team.

Merge should always be done not fast forward to keep track of all codebase changes.

---

Commandments

1. You will have no other language than English for each part of the repository: code, comments, commits, branches, issues, public documentation, README
2. You will comment the code with complex logic explaining what it does, not how it does it
3. You won't commit or push code that doesn't compile
4. You will not use names for variables that do not indicate their function
5. You will write test code for non-trivial components
6. You will check the code for runtime errors before committing or pushing it (the only exception concerns test code that must be rebased before the pull request)
7. You will rebase your branch on develop before the pull request