Thanks for helping out!
The best way to report an issue is through Github. The owners of the repo should get an email notification whenever a new issue is created.
You will need to install Git and create an account on Github to take advantage of all of the features of this template. This template also uses scripts that expect Bash to be installed at /bin/bash.
There are multiple ways to use this template as a starting point for your own project. The best way to use this is by cloning the repo to your GitHub account and creating your project with the template feature provided by Github:
The second best way to start a new project is to either clone this repo using Git and point at your own remote:
git clone --depth 1 -b main https://github.com/devlinjunker/template.github.semver.git;
mv template.github.semver <new_server_project_name>;
cd <new_server_project_name>;
git remote remove origin;
git remote add origin <new_remote_addr>;
git push --set-upstream origin main;
git checkout -b develop;
git push --set-upstream origin develop;
Or, you can download an archive of the repository contents using the Github "Download" link and extract this to access all of the files and create a new Git project with them:
After Downloading:
unzip template.github.semver-main.zip;
mv template.github.semver-main <new_server_project_name>;
cd <new_server_project_name>;
git init;
git remote add origin <remote_addr>;
git add *;
git commit;
git push;
git checkout -b develop;
git push --set-upstream origin develop
Once you have a framework and development environment chosen for your project, you should update your repo with specifics about how to install the tools and dependencies needed to run/debug/develop the application (See README for checklist).
The steps to update a Project that was created using this template, or to add these features to an existing project are the same. In the projects root directory:
git checkout main;
git remote add template https://github.com/devlinjunker/template.github.semver.git;
git fetch template;
git checkout template/main ./;
git reset HEAD * ./;
git status; # to see new files and changed files
<compare diff with `origin/main` to see updates>
git add *;
git commit;
git push;
Break down how each folder is used in the repo and how different code file types should be organized.
- .github/
|-- ISSUE_TEMPLATE/
|---- (Github Issue Template Files)
|-- workflows/
|---- (Github workflow .yaml files)
|-- (other github specific files)
- img/
|-- (project image files)
- scripts/
|-- hooks/
|---- (Git Hooks Scripts)
|-- release/
|---- (Script files that help with creating releases)
|-- workflows/
|---- (Github workflow Scripts)
- (project config files and READMEs)
Git hooks and Github workflows/actions are extremely useful for streamlining processes and typical developer actions, or verifying that standards are met. This section documents how they should be used in this project.
Git Hooks are scripts that can be run during certain parts of the Git process (after committing, before pushing, etc). Git Hooks can be added in the .git/hooks directory (I prefer to create symbolic link to another place in the repo so they can be committed for every developer. e.g. store the hook scripts in ./hooks, after git repo set up use ln -s ./hooks/ ./.git/hooks).
To create a hook, you add a script file (or symbolic link to one) in the .git/hooks/ directory with the name of the hook from this list. (e.g. to run a script before a commit is saved -- to verify the contents of the commit, verify the app builds, etc -- you would create ./.git/hooks/pre-commit).
GitHub Workflows/Actions are commands that can be run on GitHub servers, these are added in .github/workflows and defined with YAML files that express when the workflow should run and the steps it should take. Github can enforce that these workflows are successful before Pull Requests are merged via the Branch Settings Page, it can also trigger them after users perform certain actions or they can be manually triggered to run.
Shell scripts are short programs that are created to help with small tasks. They can be a part of a workflow or hook, or they can help with deployment/installation and running the final software product.
This repo has a .bulldozer.yml file that is used to customize how to automatically merge pull requests into the develop branch. This is done with the Bulldozer Github App.
The default requirements to auto-merge are:
- all required status checks passing
- a comment matching:
!mergeor! merge
View the strategies outlined in our Wiki for best practices for branching and merging new features, as well as steps to take when reviewing other submissions. The Git Hooks and Actions in this template are designed to encourage following these best strategies.
Review the Security Policy for an idea of how to submit bug reports and a review of security design principles to follow when contributing.
Once you start your project, you should update the style guide here or link to a Wiki page from here.
Some ideas of things to include in your styleguide include:
- Code Formating and (linting) tools used to ensure the style is met
- Organization of Files
- Best practices for designing new features
This template doesn't include any tests yet (although we could add them...). Once you start using this for your own project though, you should include any testing details and requirements here.
Ideas to consider for testing:
- unit tests
- integration tess
- e2e tests
- automation tests
- contract tests
- mutation tests
This template uses Semantic Versioning to label each iteration of the final project. This ensures a consitent and meaningful format for numbering releases.
Release branches are cut from the develop branch and merged into main after review. They are then tagged and marked as a release with a changelog (generated from the commit messages) of the changes made since the last release.
This process can be improved upon in projects that use this template by:
- Building and Adding code Artifacts to releases
- Including Github Milestones