NorLab Project Template

^{NorLab TeamCity GUI (VPN/intranet access)   •   norlabulaval (Docker Hub)}  

A template repository for code-related research projects. It’s meant to help kick-start repository creation by enabling software engineering research-oriented best practice.

It has a few preconfigured tools such as an initialization script to speed up the repository customization process, a pull request template, a sematic-release github action, a standardized readme file with NorLab or VAUL logo, a git ignore file with common file/directory entries, a code owner designation file, JetBranins IDE run configurations and the basic directory structure.

_{Maintainer Luc Coupal}

---

Note: For latex project such as writing proposal or conference paper, use a template from the following list of NorLab TeX template repositories instead.

How to use this template repository

• Step 1 › Generate the new repository
• Step 2 › Execute initialize_norlab_project_template.bash (Support Ubuntu and Mac OsX)
• Step 3 › Make it your own
• Step 4 › Configure the GitHub repository settings
• Step 5 › Release automation: enable semantic versioning tools

Instructions

Step 1 › Generate the new repository

1. Click on the buttons Use this template > Create a new repository
   
2. find a meaningful repository name, don't worry you can change it latter (see BC Gov Naming Repos recommendation for advice and best-practice)
3. Clone your new repository using the following command line

$ git clone --recurse-submodule https://github.com/<your-git-repository-url>

Step 2 › Execute initialize_norlab_project_template.bash

(Support Ubuntu and Mac OsX)

It will execute the following steps:

1. Install resources (or skip):
   1. (optional) Norlab Build System (NBS) submodule
   2. (optional) NorLab Shell Script Tools (N2ST) submodule
   3. (optional) semantic-release
2. Customize
   1. environment variable prefixes and shell functions project wide
   2. repository name references project wide
3. Manage readme files
   1. rename README.md to NORLAB_PROJECT_TEMPLATE_INSTRUCTIONS.md
   2. rename either README.norlab_template.md or README.vaul_template.md to README.md and delete the other one
   3. customize url references
4. Reset the content of CHANGELOG.md

Step 3 › Make it your own

1. Configure the repository directory structure for your project type
2. Modify the code owner designation file: .github/CODEOWNERS
3. Validate the content of .gitignore file
4. Modify the pull request template to fit your workflow needs: .github/pull_request_template.md
5. Make your new README.md file your own

Note: CHANGELOG.md and version.txt are both automatically generated by semantic-release

Step 4 › Configure the GitHub repository settings

★ The main branch is sacred. It must be deployable at any time.
We strongly recommend you to configure your repository branching scheme following Gitflow

main ← dev ← feature 1
           ↖ feature 2

with Branch Protection Rule enable for the default branch (i.e. main) and the dev branches.

Go to the Settings > Branches and click Add branch protection rule in the Branch Protection Rule panel

and set the following:

1. Set Branch name pattern to main
2. Set Require a pull request before merging
3. Set Require conversation resolution before merging
4. Set Restrict who can push to matching branches and add names
5. If you use a Continuous Integration service such as GitHub actions or our norlab-teamcity-server, set Require status checks to pass before merging and set Require branches to be up to date before merging
6. Repeat for the dev branch

Step 5 › Enable release automation tools (semantic versioning)

Why:

Assuming your repository is part of a bigger system,

• easily identify the repository state currently in use as a dependency
• and escape "dependency hell".

How

Any push to the main branch will trigger the execution of semantic-release which will analyse each commits message to determine the version bump following semantic versioning scheme MAJOR.MINOR.PATCH.

On version bump,

• a new repository tag gets published with the newest versions number v<MAJOR>.<MINOR>.<PATCH>
• the CHANGELOG.md and the version.txt files gets updated
• a new repository release gets published on the Releases page

Note: not each commit type triggers a version bump e.g. <type>! triggers a MAJOR version bump, feat triggers a MINOR version bump, fix andperf triggers a PATCH version bump and all others such as doc and style will register for the next release but won't trigger one.

Configuration

1. Adopt the conventional-commit specification. This is a hard requirement for semantic-release.
   See commit_msg_reference.md for a quick summary.
2. Configure the semantic-release GitHub action implemented in the .github/workflows/ directory.
   1. You must generate a GitHub personal access token
   2. and register it as a Repository Secrets in the tab Settings/secrets and variables/Actions and name it SEMANTIC_RELEASE_GH_TOKEN.
      Reference: semantic-release/GitHub Actions

---

Questions:

I'm concern using conventional-commit will slow me down:
It does not discourage moving fast, "It discourages moving fast in a disorganized way"

What if I want to revert a buggy release:
Either fix the bug and push a fix commit or revert the problematic commits and push a revert commit.

I don't want to use semantic-release or conventional-commit in my development workflow:
No problem, just disable the semantic-release github action by deleting the .github/workflows/semantic_release.yml file.