GIT

This page covers releases, tags, branches, hotfixes, merge conflicts, usable commands and maintaining the changelog.

Repositories

When you login to the Bitbucket/GitHub online interface. You are able to view all repositories:
https://bitbucket.org/dashboard/overview
https://github.com

Access

Bitbucket/GitHub admins are able to add new developers to the DPDK Team.
To add new users use these links:
https://bitbucket.org/account/user/dpdk/groups/
https://github.com/orgs/DPDK-NL/people

Basic GIT Commands

| Command | Notes | |:--------------------------------------------- |:----------------------------------- | | git clone username@host:/path/to/repository | Clones a remote repository | | git add <filename> | Add files to GIT | | git commit -m "Commit message" | Commit files with a comment | | git push | Push changes to remote GIT server | | git status | List files that are changed | | git pull | Pull changes from remote GIT server |

Release preparation / Usage of tags

• A release should always be built on a tag. A tag should have a version number which contains specific functionalities:

1. v0.1.0 (convention has a small v followed by a number)
2. v1.0.0 (the first release for production)
3. v1.1.0 (release with some new features)
4. v1.3.2 (release with bug fixes)
5. v2.0.0 (major new release)

See Semantic Versioning for more information: http://semver.org/

• When creating a release on your local machine, take in mind the following steps (preferred relative to SourceTree, or your IDE to get more experience with commands in general):

1. git pull (make sure you are up-to-date)
2. git push origin develop
3. git checkout master
4. git merge develop (Never use fast-forward!)
5. git tag (check current tag versions to decide your new tag version)
6. git tag -a v1.1 -m "Release notes"
7. git push origin master --tags

Usage of branches

• There are always 2 default branches, named master & develop. On the master branch, no new features are being developed. This branch will always contain the latest stable version which has the same contents as the version on production. (mostly attached to a tag of the latest release.)
  
• In bigger projects you will have the need for more branches than only master/develop. Every issue or specific release is managed within its own feature branch (feature/child-medicine, etc). This way we can still fix current bug fixes on the stable version for production without pushing features in develop.
• When you encounter a big issue in the production environment, you always need to create a hotfix branch based on the master branch. After finishing the fix you can create a new tag on this branch (v1.3.2 for example) and release it to production. When this fix is confirmed you can merge the hotfix back in the master branch and all other branches available in the project. This way, this bug can never return again to production. See the following commands as guide:

1. git checkout master
2. git checkout -b hotfix/bugfix-google-maps
3. git tag -a v1.3.2 -m “Bugfix notes”
4. Release & confirm if the fix is working on production
5. git checkout master
6. git merge hotfix/bugfix-google-maps
7. git tag -a v1.3.2 -m “Bugfix notes”
8. git push origin master --tags
9. git checkout develop
10. git merge hotfix/bugfix-google-maps
11. git push origin develop
12. Do the same for other necessary branches before deleting the hotfix branch
13. git branch -d hotfix/bugfix-google-maps

• For maintenance branches, the same flow applies. After maintenance is done and merged back into master & develop, make sure you leave the maintenance for next maintenance. When deploying maintenance, make sure you follow the release flow from the first chapter.

Merging & Conflicts

• It might happen that you encounter merge conflicts within your project, resolving them is really complex through the command line so use your IDE/SourceTree for this. Most reliable/known tool is PHPStorm which has great merge conflict support. In your project you can right click on the most top folder of the project and choose git -> resolve conflicts. This opens a nice diff view to resolve every individual issue of every file.
• A lot of conflicts can be prevented by pulling first before committing/pushing a new update. Pulling code regularly will help you in any use case to prevent yourself from falling behind too much. The more branches/features/people working on a project the more complex these situations can get. Be sure to ALWAYS communicate with each other (standups/walk to each other/slack) to prevent last minute merge challenges at the end of a stressful day.

Changelogs, documentation, hacks & patches

• Every git project has a README.md file by default, this file is used to document functionalities, urls and important notices about the project which every new developer has to know. The changelog, which describes every tag release, is also part of this file.
• PHPStorm has great markdown support and will show the syntax of these files including a preview mode to see the end result.
• Documentation is an important asset within every project. Anyone opening or checking out the project should be able to rely on the information within the readme file. Consider a situation when someone checks out a new project for maintenance proposes, then this person shouldn’t get stuck in the vagrant up process or miss information which could break the production environment. Sum up of examples to document:

1. API connections
2. System dependencies
3. Drupal modules that should not be updated due to known problems
4. Specific dependencies that are not running by default after vagrant up (node / solr / etc.)

• Another important section within the readme file are the applied hacks. Always list all the applied hacks referring to the specific patch which contains the actual hack itself. To add patches for every hack (so you can re-apply them after a maintenance month) follow the following steps in PHPStorm:

1. Always triple check (with colleagues / google / etc.) if the hack is the only way to solve your problem
2. When you add a hack within your code (one or more files) you create a new patch file (Tool -> create patch -> name.patch)
3. A new patch for the same feature should be named with a number (name2.patch, etc)
4. Add the patch to the _scripts/patches folder of your project

Go-Live procedure

Within the go-live moments of a project, there are a few steps which are important to keep in mind. These are important issues to ensure a solid production release, and they will return every other project.

• In the pre-live phase the test/acceptance environments should already available
• The server will have a setup which was approved on in the quote phase of the project. Depending on the project this will be done on our own hosting platform, the cloud or with an external party.
• Every issue from the go-live checklist should be reviewed to know which applies for this project. Some issues on this list apply for the last sprint (and therefore should be added in Jira), while other issues need to be checked after go-live.
• Eventually the release flow from the first chapter will be used to release the initial version to the production environment.