This document contains guidelines that all contributions to this template repo should follow. As an added benefit, these guidelines will provide a reasonable starting point for any repos based off this template.
Important
After creating a repo from this template, I'd recommend updating this document to suit your own workflows and the contents of your version-controlled document.
This repo contains a VSCode workspace to make setup easier. Simply open this repo in VSCode and install the recommended VSCode extensions:
- GitHub Actions: Useful when creating and maintaining GitHub Actions.
- LaTeX Workshop:
This extension does a majority of the heavy lifting when working with
.texfiles including preview, syntax highlighting, linting, formatting, intellisense and more. Note that this extension does have some requirements. - Paste Image:
Allows pasting images directly into markdown documents, and has been
configured in this workspace to allow pasting directly into
.texdocuments. - Trailing Spaces: This just highlights trailing whitespace, which helps keeps the document source neater.
- Code Spell Checker: A spell checker that supports most source files.
- Even Better TOML:
Adds language support for TOML, which is used by the
git-cliffconfiguration files. - Markdown All in One: This extension makes it trivial to work with Markdown files in VSCode, allowing easy previewing and linting to make repo documentation easy to maintain.
Note
Most of these extensions have been configured in the shared workspace. Any changes are detailed below.
The LaTeX Workshop extension requires a compatible LaTeX distribution to be available on the system PATH. See the installation requirements for a list of compatible distributions, and make sure you have one installed. Note that you may need to restart VSCode after installing a distribution for it to be recognised!
The following workspace settings have been configured for LaTeX Workshop:
Paste Image has been configured to allow pasting into the LaTeX document, won't be able to paste images into Markdown documents with how it has been configured in the workspace settings:
{
// Configure Paste Image to insert a LaTeX graphic when pasting an image.
"pasteImage.insertPattern": "\"\\\\begin{center}\\n\\t\\t\\\\includegraphics[width=\\\\linewidth]{${imageSyntaxPrefix}${imageFilePath}${imageSyntaxSuffix}}\\n\\t\\\\end{center}\"",
// Configure Paste Image to save images to the root images/ directory.
"pasteImage.path": "${currentFileDir}/images",
// When pasting an image, show a prompt to confirm the image path.
"pasteImage.showFilePathConfirmInputBox": true,
}Trailing Spaces has simply been configured to only automatically trim trailing whitespace from modified lines, to prevent it from causing unnecessary churn when opening large documents:
{
"trailing-spaces.deleteModifiedLinesOnly": true
}Code Spell Checker
has been configured to use en-GB by default:
{
"cSpell.language": "en-GB",
}You can easily change this to your preferred locale through the extension settings.
Markdown All in One is a great quality-of-life extension when maintaining Markdown documents. In this case it's simply configured to only generate Table of Contents (ToC) entries for levels 2 to 6, as I find it more useful than having the document heading displayed in the ToC:
{
"markdown.extension.toc.levels": "2..6",
}I've also added a couple of settings to the workspace for the editor itself:
{
// Use independent color pools for each bracket type to improve readability.
"editor.bracketPairColorization.independentColorPoolPerBracketType": true,
// Display vertical rulers at columns 80 and 100 to help maintain line length.
"editor.rulers": [
80,
100
],
// Wrap text at the specified word wrap column for better display formatting.
"editor.wordWrap": "wordWrapColumn",
}These are just visual features within the editor, but I particularly like the rulers as I prefer to keep all documents to a line length of 80 characters where possible.
This repository uses Conventional Commits. This policy is enforced automatically by a GitHub action. The fixed commit structure allows automatic document versioning and changelog generation for releases.
Conventional commits must have a type, and can optionally also include a scope. The types and scopes that will be used in this repo are defined below. Additionally, any type can be marked as a breaking change.
This section won't go into much detail about how to structure a Conventional Commit, and assumes some level of familiarity with the standard.
Important
Any changes to the types section in this document must be reflected in the git-cliff config file, to ensure that they show up in the changelogs.
Breaking changes (preferably always marked with at least a ! for visibility)
don't really have as rigid of a definition with a version controlled document as
they do in software (i.e. changes to an API), but it's worth defining what you
class as a breaking change based on the contents of your document.
For example, if you're writing a specification, it's fairly self-explanatory. In other cases, it might be used to indicate that an old section has been removed or re-worked.
Note
Remember that conventional commits are case-insensitive, except for the
BREAKING CHANGE footer which must be upper-case.
The feat and fix types are defined in the
conventional commit specification,
and are mandatory.
feat: Adding a new feature. In the context of a version-controlled document, this could indicate a new section being added to the document, or a large re-work of material.fix: Fixing a bug. In the context of a version-controlled document, this could indicate small localised changes within a section that do not affect the overall meaning (i.e. fixing typos, correcting punctuation).
Additionally, the following types are suggested by @commitlint/config-conventional, and can be used in this repo:
chore: Used for routine / maintenance tasks such as updating the.gitignore, renaming files or directories, etc.ci: Indicates changes to the CI configuration files and scripts (i.e. GitHub Actions) rather than the main document itself.docs: Changes to the surrounding documentation (i.e.README.mdandCONTRIBUTING.md) rather than the main document itself.revert: Used when reverting a previous commit.style: In the context of a version-controlled document could indicate changes to the presentation of the document rather than changes to the contents (i.e. changes to the font or the border size).
Scopes are an optional noun that may be provided with a type to provide context to the area of the repository that a commit changes.
Important
When consuming this template, the scopes in particular should be updated to suit the contents of your repo.
The following scopes are defined for this repository:
release: Changes in preparation for release, i.e. version bumps.config: Changes to configuration files used by the CI system.figures: Addition or changes to figures included in the document.
The LaTeX document contains a section for the revision history. Although a
CHANGELOG will be generated based off of the commit history when the document
is released, it can often be beneficial to keep a revision summary within the
document itself, so that it can be tracked even when printed.
This revision history must be manually edited in ./front_matter/document_revision.tex, using initials defined in ./preamble/authors.tex. This must be done as the last commit before each release, and the user should add a short summary of the revision.
This should be done using a chore(release): commit.
{ // Disable auto clean and retry for LaTeX builds, as if a build fails there is // likely an issue that requires fixing manually. "latex-workshop.latex.autoBuild.cleanAndRetry.enabled": false, // Enable cleaning of the outDir subfolders during build, as the outDir has // been specified to a non-root location. "latex-workshop.latex.clean.subfolder.enabled": true, // Specify a separate outDir to ensure that any artifacts of previews / builds // are separated from the source. "latex-workshop.latex.outDir": "%DIR%/build", }