Define a style guide for using version control with Git, specifically for use with Ignition. This includes naming for repositories, default branches, feature branches, commit messages, and pull request messages, among other things.
| Item | Style |
|---|---|
| Name | my-repository-name |
| Description | A Brief description of the repository (not empty) |
| Branch | Style |
|---|---|
| Default Branch | main |
| Development | dev |
| Release | release |
| Feature | username/my-new-feature |
| Bug Fix | username/my-bug-fix |
| Item | Default |
|---|---|
| Commit Message | Brief Commit Description |
| Item | Default |
|---|---|
| Merge Type | Merge commit or Squash |
Setting up a repository can look different depending on if one is forking an existing repo, or if using a template. These are general guidelines that can be adjusted per project specifications.
- Select whether the owner of the repository should be yourself or belong to an organization
my-repository-name
-
A unique name should be chosen for new repositories (GitHub ensures uniqueness). The name should be lower case with dashes separating words and should be reasonably clear what the repo is to be used for.
-
Good repo names:
ignition-database-frontend,this-client-test-env,exchange-dev,my-first-repo -
Bad repo names:
test,test-2,repothatneedsdelimiters
Required
- The description should expand on the name of the repo and provide a high level purpose for the codebase. Another engineer looking at this repo description should understand at a high level what to expect to see in the codebase.
Public or Private is acceptable
- This is up to the owner and depends on the intention for the repo. It is important to note that "public" on the On Prem GitHub server is still only public to the internal Inductive Automation team. No projects on the On Prem GitHub server cannot be shared or made available to the external "Public". Private will only be seen by you.
- Quickstart Project
- Collaborative projects
- Helpful team resources
- Repos to learn git
- Testing repositories
- Repos that don't follow the style guide 😤
Recommend true (false is acceptable)
- Having a readme for documentation of your project is crucial, but adding it to the initial repo is not required. It can instead be added from VSCode on your initial commit.
None (<any> is acceptable)
- Gitignore files are important to ignore files that do not need to be tracked. It is recommended not to add a .gitignore from VSCode on your initial commit.
All branches should be lower-case with dashes separating new words. In certain cases, slashes can be used to separate branch names.
After merging a feature into another branch, the feature branch should be deleted. It is recommended that branches on GitHub be set to automatically delete after a Pull Request is merged.
Main: main
- There should be no commits on this branch. Instead, use
devor a feature branch. - Historically,
masterwas used, but has fallen out of favor in recent years.mainis highly the recommended default branch name.
Development: dev
Release: release
username/my-new-feature
- Feature or bug fix branches should begin with a user to differentiate your branches from others', then have a short (1-4 words) description of the feature with the words separated by dashes (
-) - ex:
eknorr/add-test-script - ex:
jsmith/fix-readme-typos
Each commit should contain a message (git commit -m "<Commit message here>"). These messages are required by Git and should contain a brief description of what is contained in the commit. If one is not provided, a vim document will appear in the console asking for a commit message (or :q if you'd like to quit).
Some prefer to prepend commit messages with a category of the commit, such as Feature:, Chore:, Bugfix:, etc. This can be used to give a quick categorization to each commit for someone visually searching through commit messages.
📝 Note: If it's difficult to sum up your work in a brief commit message, that could be an indicator that you're trying to fit too much into a single commit. Consider breaking up the work into more than one commit.
Feature: Developed motor faceplateChore: Cleaned up messy code in myScripts/generalFixed broken binding on 'Main Views/plant'End of day commit: Halfway through my-feature
Added style class and applied it to my view and added docstrings to myScripts/general- Too many features in one commit
Built screens- Not descriptive enough
- All merges must be done through a Pull Request on GitHub
- This allows teammates to review work before merging and keeps everyone aligned on tasks
- Different types of merges exist. Recommended merge styles are:
- Merge Commit: Used to merge branches with few commits
- Squash and Merge: Used to merge branches with many commits. This option essentially makes a commit with a list of each commit in the feature branch as the default description.
If you have any questions, have a suggestion for something to add, or notice something that doesn't look right, open an issue or submit a pull request.