Skip to content

Latest commit

 

History

History
347 lines (250 loc) · 15.7 KB

_TEMPLATE_CHECKLIST.md

File metadata and controls

347 lines (250 loc) · 15.7 KB
Raw

Template checklist

When creating a new project from this template, ensure to take these steps immediately after provisioning.

Contents

1. Update all references to template-core to this Repository

After checking out the new project and setting the origin remote for git, run the following command locally to update link targets to the new Repository instead of the original template-core Repository:

Note - this assumes that you are on macOS using GNU sed installed via Homebrew as gsed. If you are running this on Linux, or otherwise have GNU sed installed as a default, simply replace gsed with sed below prior to running this command:

REPO=$(sed -E 's@.*github\.com:(.+)\.git$@\1@g' <(git ls-remote --get-url origin)); \
  find . \( -type d -name .git -prune \) -o -type f -print0 | \
  xargs -0 gsed -i "s@andrewvaughan/template-core@${REPO}@g"

For the rest of setup, refer to this - now updated - document to have accurate links to references in future steps. For the cleanest results, hold off on committing and pushing these changes until all steps in this file are complete.

2. Configure GitHub Repository settings

The GitHub template system has many limitations, only copying over files and, if selected, Branches from the parent Repository. As such, it's important to configure the Repository to the project standard prior to modifying any of the Repository files.

General settings

Visit the General Settings page for the Repository.

  • CHECK Require contributors to sign off on web-based commits

Features

  • CHECK Discussions
  • CHECK Sponsorships

Pull Requests

  • UNCHECK Allow merge commits
  • CHECK Always suggest updating pull request branches
  • CHECK Automatically delete head branches

Archives

  • CHECK Include Git LFS objects in archives

Branch and Tag protection

Visit the Rulesets page for the Repository.

In the project, visit the .github/.config/rulesets and import each of the GitHub Rulesets in the directory into the project:

  • Branch Common Rules
  • Branch Environment Rules
  • Branch Release Patterns
  • Tag Common Rules
  • Tag Release Patterns

Labels

A manual workflow called Sync Labels must trigger from the GitHub Actions page for this Repository to create the Labels necessary for automation to function and for the Software Development Lifecycle. You must trigger this workflow manually.

3. Prepare the Repository files

  • Enable git lfs for the project if, not already installed
git lfs install
  • Add and/or remove any files or folders that don't apply to this project

Optional

  • Remove all .empty files
find . -type f -name '.empty' -delete

Only for Windows-only development environments

  • Update .gitattributes and .editorconfig file endings to CRLF
  • Update all files to the new file ending in Command Prompt
for /R %f in (.*) do UNIX2DOS %f ...
for /R %f in (*.*) do UNIX2DOS %f ...

4. Select a License

Several Licenses are available based on the privileges, conditions, and limitations for Licensees of the project. Each table lists Licenses in order from least-restrictive to most-restrictive in the sections, below.

  • Remove the template-core Repository's default LICENSE file
rm LICENSE
  • Select the appropriate License using the tables, below, as a guide, and rename it to LICENSE
  • Delete all remaining LICENSE.* files
rm LICENSE.*
  • Check that all dates and copyright owners are correct
  • Update the README.md badge to show the correct License
  • Add the appropriate LICENSE boilerplate to the README.md file, if applicable
  • Add the appropriate LICENSE boilerplate to any source files, if applicable

Permissions

License File Commercial Use Distribution Modification Patent Use Private Use
LICENSE.unlicense Yes Yes Yes - Yes
LICENSE.mit Yes Yes Yes - Yes
LICENSE.apache Yes Yes Yes Yes Yes
LICENSE.gpl3 Yes Yes Yes Yes Yes
LICENSE.proprietary - - - - -

As described by:

Permission Description
Commercial Use This License grants use for commercial purpose, including derivatives
Distribution This License grants distribution of the licensed material
Modification This Licensed grants modification rights
Patent Use This License provides an express grant of patent rights from Contributors
Private Use This License grants modification rights in private

Conditions

License File Disclose Source License/Copyright Notice Same License State Changes
LICENSE.unlicense - - - -
LICENSE.mit - Yes - -
LICENSE.apache - Yes - Yes
LICENSE.gpl3 Yes Yes Yes Yes
LICENSE.proprietary - - - -

As described by:

Permission Description
Disclose Source Licensees must make source code available when distributing
License/Copyright Notice Licensees must include a copy of the License and copyright notice with the material
Same License Licensee must Release modifications under the same License when distributing the licensed material - in some cases the Licensee may use a similar or related License
State Changes Licensee must document changes made to the licensed material

Limitations

License File Limited Liability No Trademark No Warranty
LICENSE.unlicense Yes - Yes
LICENSE.mit Yes - Yes
LICENSE.apache Yes Yes Yes
LICENSE.gpl3 Yes - Yes
LICENSE.proprietary - - -

As described by:

Permission Description
Limited Liability This License includes a limitation of liability
No Trademark This License explicitly states that it doesn't grant trademark rights, even though Licenses without such a statement probably don't grant any implicit trademark rights
No Warranty This License explicitly states that it doesn't provide any warranty

5. Complete all TEMPLATE TODO items

Each file in the template that has particular needs after copying the template has those elements marked with a special TEMPLATE TODO comment.

If using VSCode, the recommended extensions and the provided workspace settings provides a curated list of items that require attention and add a counter to the bottom status bar representing how many items remain.

If not using VSCode, search for all instances of this phrase and take the actions they state:

grep -r "TEMPLATE TODO" .

Delete the TEMPLATE TODO comments in each file as you complete them.

6. Update files that can't include comments

  • Add necessary dictionaries for the expected languages to .config/linters/.cspell.json
# To list all available dictionaries
npx cspell trace -c .config/linters/.cspell.json --all ''
  • Install the recommended extensions via the prompt when first opening the workspace, or with the following command:
make vscode

7. Finishing up

With everything else complete, there is only one step left:

Next steps

Once you have refined the template project for its purpose, the following steps are usually helpful:

  1. Update the README.md file to best suit the project
  2. Prepare the .vscode folder, as described here
  3. Prepare the .devcontainer folder, as described here
  4. Update the all, build, and test-unit targets in the Makefile folder
  5. Add any specific dictionary configurations to .config/dictionaries/project.txt and .config/linters/vale/styles/Vocab/
  6. Customize the Issue and Pull Request templates

From there, it's a matter of getting started by creating new source code, tests, and build scripts to make your project a reality.

Appendix

Folder structure

This template comes with the following standard folder structure:

Folder Purpose
.build All scripts and resources tied to deployment (for example, Docker Compose)
.config All configuration files for local development
.devcontainer DevContainer configurations (GitHub Docs, VSCode Docs, Reference)
.github All configuration files for GitHub
.vscode Applicable, shared configuration files for VSCode to boost initial productivity
docs All project documentation
src All project source code
tests All test source code