Project structure

Git

Git is the version system used to maintain the programming part of this project. Some git specific guidelines of use have been adopted due to the increasing complexity of the code.

Tagging

We will use tags to statically point to commits that define a version. By definition each commit in the master branch will be tagged and will represent a version of our software, but we will explain how it is done manually.

First we need to explain how to tag a certain commit. We need to use: git tag -a "TAGNAME" -m "brief message explaining what this version does" SHA1ID_OF_THE_TAGGED_COMMIT

This will tag the commit referenced by the SHA1ID with TAGNAME and the brief message.

To push the tags to the repo we use: git push origin --tags

We can remove tags from teh local repository with: git tag -d TAGNAME

We can also delete tags from the remote server easily: git push origin --delete TAGNAME

Commit message format:

This guideline is originally defined in here. It defines a set of tags to be included in the commit message with a meaning regarding the evolution of the source code. This allows us to create a CHANGELOG.md file easily, by using own-defined tags in the commit message.

We adapt this guideline by defining:

Types of changes

• ADDED: For commits that progresses towards a feature but do not complete it.
• FINISHED: For commits that finish a feature, when is tested and ready to use.
• UPDATED: For commits that updates a finished feature such as a version update or changing a fallen link.
• CHANGED: For commits that change the implementation of a functionality but not the functionality itself.
• REMOVED: For removed features or deprecations.
• FIXED: For changes in the code that fix a bug or issue.

Format

For a short message that only includes tag and title we can use: git commit -am "TYPE_OF_CHANGE: Commit title with a complete sentence."

Notice the ":" and the space after the initial tag in the commit message: git commit -am "FIXED: Title after : and the space"

For a long message that includes tag, title and extended description we will use the command:

git commit -am "TYPE_OF_CHANGE: Commit title with a complete sentence. 

Optionally tell other things in this extended description that you want to explain about this commit. 
It can be many lines. Even an enumeration:
- like this.
- and this.
"

Notice the blankline in the long format between the title and the extended description.

For a non-changelog commit that only has extended description use:

git commit -am "
Message in commit that do not have a tag because we do not want to include them in the changelog
"`

Notice how the first line is blank in order to not include it in the changelog because it does not have a tag.

For each commit:
- [ ] Commit often. 
- [ ] Commit following these rules. 
- [ ] In case of doubt reread these guidelines. 
- [ ] If you did not, you can ammend your commits locally by using `git commit --ammend -am "FORMAT"`. This can not be done when the commit has already been pushed to the server. 
- [ ] **Check the format of the commit message before pushing**
- [ ] Each commit has to be simple and reflect its title. Is preferable doing many ADDED commits than one single FINISHED.
- [ ] Do not repeat the commit message. If you have nothing to say is preferrable that you upload an empty commit or a non-changelog commit as defined above.
- [ ] Each commit needs a limited scope. Try to keep the number of modified files to the minimum for each commit. Changes withing a commit have to be related to each other. If unrelated changes have to be performed, commit your changes and put these unrelated changes in a new commit.
- [ ] Keep lines of commit messages under 120 characters. 

## CHANGELOG.md generation

Let's define two arbitrary consecutive tags, `tag_A` and `tag_B`. In each release we would like to obtain the commit messages with the right format that have been pushed to the server between `tag_A` and `tag_B`. We can do this by using the command:

git log 'tag_A'...'tag_B'

By adding other modifiers and specifying the tags we can use this command to generate a changelog:

git log --color --decorate --oneline --pretty=format:"%C(auto)%h %d %s (%aN)" 'v0.11.0'...'HEAD' --grep="CHANGED: " --grep="ADDED: " --grep="UPDATED: " --grep="FIXED: " --grep="REMOVED: "

With a little more tweaking we could integrate this line in a CI to generate the CHANGELOG.md file on each commit into the master branch, prepending a changelog of this version to all the previous changelogs:

echo -e "CHANGES IN ACTUALVERSION: \n $(git log --color --decorate --oneline --pretty=format:"%C(auto) %d %s" 'PREVIOUSVERSION'...'ACTUALVERSION' --grep="CHANGED: " --grep="ADDED: " --grep="UPDATED: " --grep="FIXED: " --grep="REMOVED: ")\n$(cat CHANGELOG.md)" > CHANGELOG.md