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.
- 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
- Click on the buttons
Use this template
>Create a new repository
- find a meaningful repository name, don't worry you can change it latter (see BC Gov Naming Repos recommendation for advice and best-practice)
- Clone your new repository using the following command line
$ git clone --recurse-submodule https://github.com/<your-git-repository-url>
(Support Ubuntu and Mac OsX)
It will execute the following steps:
- Install resources (or skip):
- (optional) Norlab Build System (NBS) submodule
- (optional) NorLab Shell Script Tools (N2ST) submodule
- (optional) semantic-release
- Customize
- environment variable prefixes and shell functions project wide
- repository name references project wide
- Manage readme files
- rename
README.md
toNORLAB_PROJECT_TEMPLATE_INSTRUCTIONS.md
- rename either
README.norlab_template.md
orREADME.vaul_template.md
toREADME.md
and delete the other one - customize url references
- rename
- Reset the content of
CHANGELOG.md
- Configure the repository directory structure for your project type
- Modify the code owner designation file:
.github/CODEOWNERS
- Validate the content of
.gitignore
file - Modify the pull request template to fit your workflow needs:
.github/pull_request_template.md
- Make your new
README.md
file your own
Note: CHANGELOG.md
and version.txt
are both automatically generated
by semantic-release
★ 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:
- Set Branch name pattern to
main
- Set Require a pull request before merging
- Set Require conversation resolution before merging
- Set Restrict who can push to matching branches and add names
- 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
- Repeat for the
dev
branch
Assuming your repository is part of a bigger system,
- easily identify the repository state currently in use as a dependency
- and escape "dependency hell".
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
.
- a new repository tag gets published with the newest versions number
v<MAJOR>.<MINOR>.<PATCH>
- the
CHANGELOG.md
and theversion.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.
- Adopt the conventional-commit specification. This is a hard requirement for semantic-release.
See commit_msg_reference.md for a quick summary. - Configure the semantic-release GitHub action implemented in the
.github/workflows/
directory.- You must generate a GitHub personal access token
- and register it as a Repository Secrets in the tab
Settings/secrets and variables/Actions
and name itSEMANTIC_RELEASE_GH_TOKEN
.
Reference: semantic-release/GitHub Actions
I'm concern using conventional-commit will slow me down:
It does not discourage moving fats, "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.