diff --git a/.config/dictionaries/ops.txt b/.config/dictionaries/ops.txt index d1fd90d..22eed71 100644 --- a/.config/dictionaries/ops.txt +++ b/.config/dictionaries/ops.txt @@ -24,6 +24,7 @@ eamodio ecrc esbenp Gruntfuggly +gsed KICS linkcheckmd Makefiles diff --git a/.mega-linter.yml b/.mega-linter.yml index b98da28..96c366d 100644 --- a/.mega-linter.yml +++ b/.mega-linter.yml @@ -136,7 +136,7 @@ SPELL_VALE_FILTER_REGEX_EXCLUDE: (\.config\/linters\/vale\/styles\/(Google\/.+|V # - Vale style guide dependencies # # TODO Also temporarily ignores GitHub Issue templates due to problem with schema update. -# @link https://github.com/andrewvaughan/template-core/issues/44 +# @link http://tinyurl.com/tplcore44 # YAML_V8R_FILTER_REGEX_EXCLUDE: (\.config\/linters\/vale\/styles\/Google\/.*|\.github/ISSUE_TEMPLATE/.*\.yml) diff --git a/_TEMPLATE_CHECKLIST.md b/_TEMPLATE_CHECKLIST.md index dc0c28c..db876bf 100644 --- a/_TEMPLATE_CHECKLIST.md +++ b/_TEMPLATE_CHECKLIST.md @@ -2,12 +2,12 @@ When creating a new project from this template, ensure to take these steps immediately after provisioning. + ## Contents - [Template checklist](#template-checklist) - - [Pre-steps](#pre-steps) - [1. Configure GitHub Repository settings](#1-configure-github-repository-settings) - [General settings](#general-settings) - [Features](#features) @@ -15,40 +15,24 @@ When creating a new project from this template, ensure to take these steps immed - [Archives](#archives) - [Branch and Tag protection](#branch-and-tag-protection) - [Labels](#labels) - - [2. Configure files for new project](#2-configure-files-for-new-project) - - [3. Select a license](#3-select-a-license) + - [2. Configure the Repository for `git-lfs`](#2-configure-the-repository-for-git-lfs) + - [3. Update all references to `template-core` to this Repository](#3-update-all-references-to-template-core-to-this-repository) + - [4. Configure prepared files and directories for new project](#4-configure-prepared-files-and-directories-for-new-project) + - [Only for Windows-only development environments](#only-for-windows-only-development-environments) + - [5. Select a license](#5-select-a-license) - [Permissions](#permissions) - [Conditions](#conditions) - [Limitations](#limitations) - - [4. Complete all `TEMPLATE TODO` items](#4-complete-all-template-todo-items) - - [5. Update files that can't include comments](#5-update-files-that-cant-include-comments) - - [6. Finishing up](#6-finishing-up) + - [6. Complete all `TEMPLATE TODO` items](#6-complete-all-template-todo-items) + - [7. Update files that can't include comments](#7-update-files-that-cant-include-comments) + - [8. Finishing up](#8-finishing-up) - [Next steps](#next-steps) - [Appendix](#appendix) - [Folder structure](#folder-structure) --- - -## Pre-steps - -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`][template-core] Repository: - -```sh -REPO=$(sed -E 's@.*github\.com:(.+)\.git$@\1@g' <(git ls-remote --get-url origin)); \ - sed -i "s@/andrewvaughan/template-core@/${REPO}@g" _TEMPLATE_CHECKLIST.md -``` - -> **Note:** If on FreeBSD/macOS, install [`gnu-sed`][homebrew-sed] or use this slightly altered command, instead: -> -> ```sh -> REPO=$(sed -E 's@.*github\.com:(.+)\.git$@\1@g' <(git ls-remote --get-url origin)); \ -> sed -i "" "s@/andrewvaughan/template-core@/${REPO}@g" _TEMPLATE_CHECKLIST.md -> ``` - -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. + ## 1. Configure GitHub Repository settings @@ -100,14 +84,10 @@ manually. --- -## 2. Configure files for new project - -- [ ] Add and/or remove any files or [folders](#folder-structure) that don't apply to this project -- [ ] Remove all `.empty` files +## 2. Configure the Repository for `git-lfs` -```bash -find . -type f -name '.empty' -delete -``` +Configuring the Repository to use `git-lfs` properly will diverge the Repository and require a force-push. As such, it's +much better to do this at the beginning of your process: - [ ] Enable `git lfs` for the project @@ -115,15 +95,60 @@ find . -type f -name '.empty' -delete git lfs install ``` -- [ ] Migrate any existing binary files to be `lfs` supported +- [ ] Migrate any existing binary files to be `lfs` supported and run garbage collection to prune the branch size + +> **Important!** This entirely rewrites your branch, so you must perform a force-push after these steps. ```sh -git lfs migrate import --everything +git lfs migrate import --everything --yes +git gc --prune=now +git push --force +``` + +--- + +## 3. 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`][template-core] Repository: + +> **Note** - this assumes that you are on macOS using GNU `sed` installed via [Homebrew][homebrew-sed] 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: + +```sh +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. + +--- + +## 4. Configure prepared files and directories for new project + +- [ ] Add and/or remove any files or [folders](#folder-structure) that don't apply to this project +- [ ] Remove all `.empty` files + +```bash +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 + +```bat +for /R %f in (.*) do UNIX2DOS %f ... +for /R %f in (*.*) do UNIX2DOS %f ... ``` --- -## 3. Select a license +## 5. Select a license Several [Licenses][choose-a-license] 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. @@ -149,7 +174,7 @@ rm LICENSE.* ### Permissions | License File | Commercial Use | Distribution | Modification | Patent Use | Private Use | -| :------------------------------- | :------------: | :----------: | :----------: | :--------: | :---------: | +|:---------------------------------|:--------------:|:------------:|:------------:|:----------:|:-----------:| | [`LICENSE.unlicense`][unlicense] | Yes | Yes | Yes | - | Yes | | [`LICENSE.mit`][mit] | Yes | Yes | Yes | - | Yes | | [`LICENSE.apache`][apache2] | Yes | Yes | Yes | Yes | Yes | @@ -159,7 +184,7 @@ rm LICENSE.* 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 | @@ -169,7 +194,7 @@ As described by: ### Conditions | License File | Disclose Source | License/Copyright Notice | Same License | State Changes | -| :------------------------------- | :-------------: | :----------------------: | :----------: | :-----------: | +|:---------------------------------|:---------------:|:------------------------:|:------------:|:-------------:| | [`LICENSE.unlicense`][unlicense] | - | - | - | - | | [`LICENSE.mit`][mit] | - | Yes | - | - | | [`LICENSE.apache`][apache2] | - | Yes | - | Yes | @@ -181,7 +206,7 @@ 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 | @@ -192,7 +217,7 @@ As described by: ### Limitations | License File | Limited Liability | No Trademark | No Warranty | -| :------------------------------- | :---------------: | :----------: | :---------: | +|:---------------------------------|:-----------------:|:------------:|:-----------:| | [`LICENSE.unlicense`][unlicense] | Yes | - | Yes | | [`LICENSE.mit`][mit] | Yes | - | Yes | | [`LICENSE.apache`][apache2] | Yes | Yes | Yes | @@ -204,7 +229,7 @@ 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 | @@ -213,7 +238,7 @@ As described by: --- -## 4. Complete all `TEMPLATE TODO` items +## 6. 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. @@ -231,7 +256,7 @@ Delete the `TEMPLATE TODO` comments in each file as you complete them. --- -## 5. Update files that can't include comments +## 7. Update files that can't include comments - [ ] Add necessary dictionaries for the expected languages to `.config/linters/.cspell.json` @@ -248,7 +273,7 @@ make vscode --- -## 6. Finishing up +## 8. Finishing up With everything else complete, there is only one step left: @@ -285,7 +310,7 @@ This template comes with the following standard folder structure: | Folder | Purpose | -| :----------------------------- | :--------------------------------------------------------------------------------------------- | +|:-------------------------------|:-----------------------------------------------------------------------------------------------| | [.build](.build) | All scripts and resources tied to deployment (for example, Docker Compose) | | [.config](.config) | All configuration files for local development | | [.devcontainer](.devcontainer) | DevContainer configurations ([GitHub Docs][dc-gh], [VSCode Docs][dc-vsc], [Reference][dc-ref]) |