Gitlab Work-Flow¶

To fully exploit Gitlab features, the work-flow should start with the creation of a new issue and a related merge request and branch.

To do this, go to the Gitlab website and navigate to your repository.

Click on issues and open a new issue describing the fix you are to implement or the new feature you want to introduce. Once you have an issue, you can open a merge request marked as Draft (i.e. work in progress) and a new branch simply by clicking Create merge request inside the issue overview.

Note

From Gitlab 13, Work In Progress (WIP) merge requests have been renamed Draft. More info here

When creating the merge request, you can write the MINOR_VERSION or MAJOR_VERSION keywords in the merge request description, to tell Hog how to tag the repository once the source branch is merged into your official branch.

Now that you have a new branch connected to the issue, on your local machine, navigate to your local project folder and checkout the new branch.

You can now develop your new feature or commit the code you have.

Once you are done with your changes, you are ready to start the Hog CI.

To do this, you need to solve the Draft status. This can be done either by going to the Merge Request page in the Gitlab web-site and click on the Mark as ready button,

or (thanks to a Hog feature) you can start your commit message with RESOLVE_WIP: from the command line.

  git add new_files
  git commit -m "RESOLVE_WIP: <my message>"
  git push

If you opt for the website method, remember that you need to push another commit afterwards to start the CI. Once the pipeline passes and your changes are approved, if required, you can merge your source branch simply by clicking on the merge button in the merge request.

Create a Merge Request without an issue¶

You can avoid using issues by creating a new branch and a merge request connected to your branch. You can still use the nice Draft feature by adding [Draft] or Draft: at the beginning of the title of the merge request: the merge request will be marked as work in progress.

Commit your code and accidental commits¶

If you have already some uncommitted/committed new features, you should create a new branch, commit your code there and create a new merge request when ready.

If you have already committed your changes to a wrong branch (e.g. the master) simply reset that branch to the latest correct commit, e.g.

  git reset --hard <latest_correct_commit_hash>
  git push origin master

Create a new branch, check it out and commit your code there. To avoid direct commit to the master (or official) branch, you can configure the repository to forbid pushing directly to the some special branch, for example master.

To do this go to Settings and then Repository on Gitlab website. Then expand Protected Branches and add the branches that you want to protect.

Increasing version number¶

Hog uses a version of the form vM.m.p. Where M is the major version, m is the minor version and p is the patch. You will be able to increase the different levels of version by editing the merge request description.

The major version number can be increased by placing MAJOR_VERSION in the merge request description. While merging the merge request Hog will read the description, find the MAJOR_VERSION keyword and increase the major version counter. This will also reset the minor and patch counters.

The minor version number can be increased by placing MINOR_VERSION in the merge request description. While merging the merge request Hog will read the description, find the MINOR_VERSION keyword and increase the minor version counter. This will also reset the patch counters.

The patch number will be increased automatically at each accepted merge request. While merging the merge request Hog will read the description, find no keyword and increase the patch counter.

Examples¶

Let’s suppose the last tag of your firmware is v1.2.4, the possible scenarios are:

Merge request description	Original version	Final version
without any keyword	v1.2.4	v1.2.5
contains `MINOR_VERSION` keyword	v1.2.4	v1.3.0
contains `MAJOR_VERSION` keyword	v1.2.4	v2.0.0

Gitlab Releases¶

When creating a new tag, Hog CI will also create a new release, if the __HOG_CREATE_OFFICIAL_RELEASE__ variable is set to 1. The release contains the project versions and stores the binary files and logs, as derived from the Collect Artifacts job. In case of multiple projects, the release will always contain the latest available binaries. If a project was not generated in the current release (e.g. because it was not modified), the binaries attached to the release will be taken from the previous tag.
Hog has also the ability to write automatically the release note, by looking at the merge request commit messages. If you want a commit message to be included in the release note, you should start your commit message with the FEATURE: keyword. For example:

  git commit -m "FEATURE: Some awesome update"

Intermediate build branches¶

Warning

This feature is not available with the dynamic CI.

A novel feature of Hog2021.1 allows to execute a different CI build for Merge Request targeting an intermediate build branch. A possible use-case for this feature would be in the event that you have a large firmware, which you want to build only when the compilation of its individual module is successful.

To do that, you have to declare your intermediate branch in the global HOG_INTERMEDIATE_BRANCH CI/CD variable. Then you have to select the projects that you wish to run for the intermediate branch MR, by setting to 1 the INTERMEDIATE_BUILD variable in your .gitlab-ci.yml for the chosen project. For example,

generate_project:my_project:
    extends: .generate_project
    variables:
      extends: .vars
      PROJECT_NAME: my_project
      INTERMEDIATE_BUILD: "1"

simulate_project:my_project:
    extends: .simulate_project
    variables:
      extends: .vars
      PROJECT_NAME: my_project
      INTERMEDIATE_BUILD: "1"

In this case, CI workflow for project my_project would start only for merge requests towards the HOG_INTERMEDIATE_BRANCH.

Note

Merging branches into HOG_INTERMEDIATE_BRANCH do not activate any subsequent pipeline. You have to open manually another MR from HOG_INTERMEDIATE_BRANCH to HOG_TARGET_BRANCH, if you wish to propagate your changes.