NorLab Project Template

^{Dockerized-NorLab project app (DNA)   •   NorLab Docker Hub   •   NorLab TeamCity (vpn/intranet)}

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.

_{Maintainer Luc Coupal}

---

Table Of Contents

• NorLab Project Template
  • Getting started (fast)
    • Requirements:
    • Install steps:
      • Step 1 › Generate the new repository from template and clone it
      • Step 2 › Execute initialization script
      • Step 3 › (Optional) Configure semantic-release GitHub token
      • Step 4 › Make it your own
  • What it does
  • Instructions (detailed)
  • Step 1 › Generate the new repository (detailed)
  • Step 2 › Execute initialization script (detailed)
  • Step 3 › (Optional) Configure semantic-release GitHub token (detailed)
  • Step 4 › Make it your own (detailed)
  • Documentation
    • Configure the GitHub repository settings manually
      • Why
      • What
      • Configuration
      • Method 1: Automated configuration
      • Method 2: Manual configuration
    • Enable release automation tools (semantic versioning)
      • Why
      • How it work
      • Configuration
      • References
  • Questions
    • I'm concern using conventional-commit will slow me down:
    • What if I want to revert a buggy release:
    • I don't want to use semantic-release or conventional-commit in my development workflow:

Getting started (fast)

Requirements:

• GitHub CLI (gh) ⟶ See install instruction at https://cli.github.com
• Command-line JSON processor (jq):
  • Linux ⟶ $ sudo apt-get update && sudo apt-get install jq
  • MacOs ⟶ $ brew update && brew install jq
• Directory visualization command (tree):
  • Linux ⟶ $ sudo apt-get update && sudo apt-get install tree
  • MacOs ⟶ $ brew update && brew install tree

Install steps:

Step 1 › Generate the new repository from template and clone it

Click on the buttons Use this template > Create a new repository, then

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

Go to detailed instructions →

Step 2 › Execute initialization script

Execute the initialization script and follow the instruction on console

cd /your/new/git/repository/root/
bash initialize_norlab_project_template.bash

Go to detailed instructions →

Step 3 › (Optional) Configure semantic-release GitHub token

Generate a GitHub personal access token and execute

$ gh secret set SEMANTIC_RELEASE_GH_TOKEN --body "<your-generated-token-value>"

See commit_msg_reference.md for a quick summary of the conventional-commit specification commit message formating requirements.

Go to detailed instructions →

Step 4 › Make it your own

Go to detailed instructions →

🦾

---

What it does

This template repository has a few preconfigured tools such as

• an initialization script to speed up the repository customization process,
• a GitHub branch protection rule configuration script,
• a sematic-release github action,
• a standardized readme file with NorLab or VAUL logo,
• a git ignore file with common file/directory entries,
• a pull request template,
• a code owner designation file,
• a JetBrains IDE run configurations and Junie AI guidelines
• and the basic directory structure.

The initialization script perform the following:

• Customize the repository files to your need
• Configure the GitHub branch protection rule
• Optional install:
  • semantic-release automation,
  • norlab-shell-script-tools,
  • norlab-build-system.

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

---

Instructions (detailed)

Install steps:

• Step 1 › Generate the new repository (detailed)
• Step 2 › Execute initialization script (detailed)
• Step 3 › (Optional) Configure semantic-release GitHub token (detailed)
• Step 4 › Make it your own (detailed)

Documentation

• Configure the GitHub repository settings manually
• Enable release automation tools (semantic versioning)

Questions

• I'm concern using conventional-commit will slow me down:
• What if I want to revert a buggy release:
• I don't want to use semantic-release or conventional-commit in my development workflow:

Step 1 › Generate the new repository (detailed)

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-new-git-repository-url>

Step 2 › Execute initialization script (detailed)

(Support Unix system: Ubuntu and Mac OsX)

# From repository root, execute the following line
$ bash initialize_norlab_project_template.bash

# Follow the instruction on the console

The initialization script 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
   4. (optional) JetBrains IDE resources: run configuration and Junie AI guidelines
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
5. Configure the GitHub branch protection rule

When the script execution is done, you will end up with the following repository structure:

Minimal install

my_new_cool_repo/
 ├── .github/
 │   ├── CODEOWNERS
 │   └── pull_request_template.md
 ├── src/
 │   ├── README.md
 │   └── dummy.bash
 ├── tests/
 │   └── README.md
 ├── artifact/
 │   └── README.md
 ├── utilities/
 ├── visual/
 │   └── ...
 ├── to_delete/                                   <-- to delete when done
 │   ├── NORLAB_PROJECT_TEMPLATE_INSTRUCTIONS.md 
 │   ├── configure_github_branch_protection.bash 
 │   └── initialize_norlab_project_template.bash 
 ├── .gitignore
 ├── .gitmodules
 ├── commit_msg_reference.md
 └── README.md

Full install

my_new_cool_repo/
 ├── .github/
 │   ├── CODEOWNERS
 │   ├── pull_request_template.md
 │   └── workflows
 │       └── semantic_release.yml                 <-- Semantic-versioning (optional)
 ├── .junie/                                      <-- LLM/AI agent instructions
 │   ├── ai_ignored/
 │   │   ├── recipes.md
 │   │   └── scratch.md
 │   ├── active_plans/
 │   └── guidelines.md
 ├── .run/                                        <-- JetBrains run configuration
 │   ├── openATerminalInUbuntuContainer.run.xml
 │   └── runBatsTestsAll.run.xml                  <-- norlab-shell-script-tools (optional)
 ├── src/
 │   ├── README.md
 │   └── dummy.bash
 ├── tests/
 │   ├── README.md
 │   ├── run_bats_core_test_in_n2st.bash          <-- norlab-shell-script-tools (optional)
 │   └── tests_bats/                              <-- norlab-shell-script-tools (optional)
 │       └── ...
 ├── artifact/
 │   └── README.md
 ├── utilities/
 │   ├── norlab-build-system                      <-- optional
 │   └── norlab-shell-script-tools                <-- optional
 ├── visual/
 │   └── ...
 ├── to_delete/                                   <-- to delete when done
 │   ├── NORLAB_PROJECT_TEMPLATE_INSTRUCTIONS.md 
 │   ├── configure_github_branch_protection.bash 
 │   └── initialize_norlab_project_template.bash 
 ├── .env.my_new_cool_repo                         <-- norlab-shell-script-tools (optional)
 ├── .aiignore
 ├── .gitignore
 ├── .gitmodules
 ├── .releaserc.json                               <-- Semantic-versioning (optional)
 ├── CHANGELOG.md                                  <-- Semantic-versioning (optional)
 ├── version.txt                                   <-- Semantic-versioning (optional)
 ├── commit_msg_reference.md
 └── README.md

Step 3 › (Optional) Configure semantic-release GitHub token (detailed)

Required if installed semantic-release

1. Generate a GitHub personal access token
2. and register the generated token on your repository as a Repository Secrets named SEMANTIC_RELEASE_GH_TOKEN:
   • method 1: using GitHub cli, using command

     # From repository root
     $ gh secret set SEMANTIC_RELEASE_GH_TOKEN --body "<your-generated-token-value>"

   • method 2: see manual install method in Documentation section Release automation: enable semantic versioning tools / Configuration

Step 4 › Make it your own (detailed)

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

Documentation

Configure the GitHub repository settings manually

Why

Release branches are sacred, they must be deployable at any given time (e.g., the main branch).
Doing research is already hard enough. The last thing any researcher want is to throw an unreliable code base into the mix.

What

VCS conventions:

• The repository default branch (the one who is checked out by default when cloning) should be either the main release branch or a pre-release branch.
• The name main or master are conventions for the main release branch.
• For ROS base specific repository, branch named after ROS distro are usually considered release branch, e.g., foxy. humble
• The name dev, devel or develop are conventions for the bleeding edge branch.
• The name beta and alpha are conventions for pre-release branch.
• Branches prefixed release* are usually release preparation branch, published releases are merged into release branches and tagged.

We strongly recommend you configure your repository following Gitflow branching scheme

                                                      tag:release-1
── main ────────────────────────────────────────────────────┴─────▶︎
     └─ develop ──────────────────────────────────────────┴──────▶︎
                   └─ feature 1 ───┘    └─ feature 2 ───┘

with Branch Protection Rule enable for the release, pre-release and bleeding edge branches.

Configuration

Method 1: Automated configuration

Use the provided configuration script and follow the instructions on console

bash configure_github_branch_protection.bash

Method 2: Manual configuration

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
   • Set Require approvals with default number to 1
   • Set Dismiss stale pull request approvals when new commits are pushed
   • Set Require review from Code Owners
3. Set Require status checks to pass before merging
   • Set Require branches to be up to date before merging;
   • (Optional) If you use a Continuous Integration service such as GitHub actions or our norlab-teamcity-server, add the Status check tahat are required name.
4. Set Require conversation resolution before merging
5. Set Restrict who can push to matching branches
6. Repeat for the dev branch

Enable release automation tools (semantic versioning)

Why

Assuming your repository is part of a bigger system,

• quickly identify the state of each repository dependencies,
• and escape "dependency hell".

How it work

Any push to a release or pre-release branch will trigger the execution of semantic-release which will analyze 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. Generate a GitHub personal access token
2. and register the generated token on your repository as a Repository Secrets named SEMANTIC_RELEASE_GH_TOKEN:
   • method 1: using GitHub cli, using command

     # From repository root
     $ gh secret set SEMANTIC_RELEASE_GH_TOKEN --body "<your-generated-token-value>"

   • method 2: via your repository GitHub web page by going to the Settings/secrets and variables/Actions tab, add a Repository Secrets with the name SEMANTIC_RELEASE_GH_TOKEN.
3. Modify the semantic-release GitHub action implemented in .github/workflows/semantic_release.yml if necessary. The current configuration should do the trick for most use cases.
4. Adopt the conventional-commit specification. This is a hard requirement for semantic-release.
   See commit_msg_reference.md for a quick summary.

References

• semantic-release/GitHub Actions
• GitHub
  • Personal access token
  • Creating a personal access token for the command line

---

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.