Fixed issue with links not being fixed globally (closes #73) (#74)

* Fixed issue with links not being fixed globally (closes #73) * Cleaned up template checklist * [MegaLinter] Apply linters fixes --------- Co-authored-by: andrewvaughan <[email protected]>
andrewvaughan · Jan 15, 2024 · 2756889 · 2756889
1 parent c57baf5
commit 2756889
Show file tree

Hide file tree

Showing 3 changed files with 73 additions and 47 deletions.
diff --git 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
@@ -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
@@ -2,53 +2,37 @@
 
 When creating a new project from this template, ensure to take these steps immediately after provisioning.
 
+<!-- editorconfig-checker-disable -->
 <!-- prettier-ignore-start -->
 <!-- omit from toc -->
 ## 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)
       - [Pull Requests](#pull-requests)
       - [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)
 
 ---
 <!-- prettier-ignore-end -->
-
-## 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.
+<!-- editorconfig-checker-enable -->
 
 ## 1. Configure GitHub Repository settings
 
@@ -100,30 +84,71 @@ 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
 
 ```sh
 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:
 <!-- editorconfig-checker-disable -->
 
 | 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:
 <!-- editorconfig-checker-disable -->
 
 | 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:
 <!-- editorconfig-checker-disable -->
 
 | 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]) |