! FAQ

What is this "Template" for?

This is a starting point for programming projects that use Semantic Versioning.

It contains template documentation files for starting the project with Git Hooks and Github Action scripts plus Github Apps that enforce a standardized development process with Semantic Versioning.

What is Semantic Versioning?

Semantic Versioning is a set of rules and grammar for version numbers and how they should be assigned and incremented.

The rules are designed around a numbering system that follows an X.Y.Z pattern with additional suffixes if needed. The X is the major version number, the Y is the minor version number and the Z is the patch version number. The rules define when these can be incremented and that the released package should not be modified without modifying the version number and releasing a new version.

How do I use this "Template"?

See CONTRIBUTING.md for detailed instructions.

You can clone this repository and then use it as a template for your project by removing the 
initial remote and setting your own Github remote. 

- OR - 

You can fork this repository to your Github Account and then use the `Use Template` feature when 
creating new repositories on Github. 

Once you have the project initialized, follow the Quick Setup and Run Instructions in the README to make sure you update all of the pieces for your project.

What Programming Language do I need to use?

You can use any programming language! This project is meant to be language agnostic, however I do recommend you look into Shell Scripting(hooks/) and Github Actions(workflows/) in order to understand how the script files work in this template.

How do I use the Git Hooks?

The Git Hooks are script files that will be run on your local development machine. See the detailed instructions here. You will need to navigate to the .git/hooks directory in your local repository and create symbolic links to each hook script file with:

ln -s ../../scripts/hooks/<HOOK_NAME>.sh <HOOK_NAME>

How do I use the GitHub Actions?

There are two types of Actions in this template: Semi-Automated and Fully Automated.

The Semi-Automated GitHub Actions will be available in your GitHub repository in the Repository header navigation bar under the Actions Tab. You will then need to trigger them automatically by:

1. Selecting the name in the menu panel on the left
2. Pressing the Run Workflow button

The Fully Automated Actions should run when specific events occur such as PR creation or editing, pushing commits to PR branches, PR comments or on merge to main branch.

How do I create a Release?

Minor releases should be created by the release-cut Github Action automatically once a feature/ or feat/ branch has been merged automatically by Bulldozer (should be squash and merged with feature:* or feat:* commit message).

To create the release:

1. Navigate to the `Actions tab
2. Select the release-cut Action
3. Press the Run Workflow Button and ensure develop is selected then press Run

Major releases will need more manual intervention by the repository administrator

How do I Patch a Release?

Patching is a more manual process. The Automated patch-cut action will create a patch-* branch off of the most recent main commit to update the most recent release.

After the developer has checked out the patch-* branch and committed their fix, the developer will need to manually create a PR into the main branch. Once the patch-* PR is manually merged (without squashing), the Automated GitHub Actions should take over to Tag and Create a GitHub release with release notes that contain the commit messages from the patch branch.

Updating a previous release is a fully manual process