diff --git a/.config/docs/blueprint-contributing.md b/.config/docs/blueprint-contributing.md index 3c7f639..d94d965 100644 --- a/.config/docs/blueprint-contributing.md +++ b/.config/docs/blueprint-contributing.md @@ -8,4 +8,5 @@ {{ load:.config/docs/contributing/testing.md }} {{ load:.config/docs/contributing/pull-requests.md }} {{ load:.config/docs/common/contributing/styleguides.md }} +{{ load:.config/docs/common/contributing/troubleshooting.md }} {{ load:.config/docs/common/contributing/contributors.md }} diff --git a/Taskfile.yml b/Taskfile.yml index a78dd92..f3a57ca 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -1,5 +1,6 @@ --- version: '3' + includes: ansible: taskfile: ./.config/taskfiles/ansible/Taskfile.yml @@ -301,7 +302,9 @@ includes: web:profile: taskfile: ./.config/taskfiles/web/Taskfile-profile.yml optional: true + output: interleaved + vars: DOCKERHUB_PROFILE: sh: | @@ -354,7 +357,11 @@ vars: GROUP_EXEC_ASYNC: 'false' # yamllint disable rule:line-length IGNORE_FOLDERS: >- - -path './.autodoc/*' -o -path './.cache/*' -o -path './.common*' -o -path './.config/*' -o -path './.git/*' -o -path './.modules/*' -o -path './.npm/*' -o -path './.pnpm-store/*' -o -path './.shared/*' -o -path './.task/*' -o -path './.venv/*' -o -path './.vscode/*' -o -path './build/*' -o -path './dist/*' -o -path './node_modules/*' -o -path './roles/*' -o -name pnpm-lock.yaml -o -name package-lock.json -o -name poetry.lock -o -name '.variables.json' -o -name '.git' + -path './.autodoc/*' -o -path './.cache/*' -o -path './.common*' -o -path './.config/*' -o -path './.git/*' -o + -path './.modules/*' -o -path './.npm/*' -o + -path './.pnpm-store/*' -o -path './.shared/*' -o -path './.task/*' -o -path './.venv/*' -o -path './.vscode/*' -o + -path './build/*' -o -path './dist/*' -o -path './node_modules/*' -o -path './roles/*' -o -name pnpm-lock.yaml -o + -name package-lock.json -o -name poetry.lock -o -name '.variables.json' -o -name '.git' INIT_SCRIPT: https://gitlab.com/megabyte-labs/gitlab-ci/-/raw/master/scripts/update-init.sh LOG_FIX: sh: chmod +x .config/log @@ -371,7 +378,7 @@ vars: fi PROJECT_TYPE: sh: | - if type jq &> /dev/null && [ -f package.json ]; then VER="$(jq -r '.blueprint.group' package.json)"; if [ "$VER" == 'null' ]; then echo TYPE="$GROUP_TYPE"; else TYPE="$VER"; fi; else TYPE="$GROUP_TYPE"; fi + if type jq &> /dev/null && [ -f package.json ]; then VER="$(jq -r '.blueprint.group' package.json)"; if [ "$VER" == 'null' ]; then TYPE="$GROUP_TYPE"; else TYPE="$VER"; fi; else TYPE="$GROUP_TYPE"; fi if type jq &> /dev/null && [ -f package.json ]; then VER="$(jq -r '.blueprint.subgroup' package.json)"; if [ "$VER" == 'null' ]; then SUBTYPE="$REPOSITORY_TYPE"; else SUBTYPE="$VER"; fi; else SUBTYPE="$REPOSITORY_TYPE"; fi if [ "$TYPE" == 'common' ] && [ "$SUBTYPE" == 'shared' ]; then echo 'shared' @@ -394,13 +401,34 @@ vars: fi PYTHON_VIRTUALENV: true REPOSITORY_SUBTYPE: - sh: if type jq &> /dev/null && [ -f package.json ]; then VER="$(jq -r .blueprint.subgroup package.json)"; if [ "$VER" == null ]; then echo "$REPOSITORY_TYPE"; else echo "$VER"; fi; else echo "$REPOSITORY_TYPE"; fi + sh: | + if [ -n "$REPOSITORY_TYPE" ]; then REPO_SUBTYPE="$REPOSITORY_TYPE"; fi + if type jq &> /dev/null && [ -f package.json ]; then + VER="$(jq -r '.blueprint.subgroup' package.json)" + if [ "$VER" == 'null' ]; then + if [ -n "$REPO_SUBTYPE" ]; then echo "$REPO_SUBTYPE"; else echo "misc"; fi + else + echo "$VER" + fi + else + if [ -n "$REPO_SUBTYPE" ]; then echo "$REPO_SUBTYPE"; else echo "misc"; fi + fi REPOSITORY_TYPE: - sh: if type jq &> /dev/null && [ -f package.json ]; then VER="$(jq -r .blueprint.group package.json)"; if [ "$VER" == null ]; then echo "$GROUP_TYPE"; else echo "$VER"; fi; else echo "$GROUP_TYPE"; fi + sh: | + if [ -n "$GROUP_TYPE" ]; then REPO_TYPE="$GROUP_TYPE"; fi + if type jq &> /dev/null && [ -f package.json ]; then + VER="$(jq -r '.blueprint.group' package.json)" + if [ "$VER" == 'null' ]; then + if [ -n "$REPO_TYPE" ]; then echo "$REPO_TYPE"; else echo "misc"; fi + else + echo "$VER" + fi + else + if [ -n "$REPO_TYPE" ]; then echo "$REPO_TYPE"; else echo "misc"; fi + fi SEMANTIC_CONFIG: semantic-release-config TIMEZONE: America/New_York - includes: - common:start: ./.config/taskfiles/common/Taskfile-start.yml + env: GOPATH: sh: | @@ -421,6 +449,7 @@ env: PATH="$PATH:$HOME/.local/go/bin:$HOME/go/bin" PATH="$PATH:/home/linuxbrew/.linuxbrew/bin:/home/linuxbrew/.linuxbrew/sbin" PATH="$PATH:$PWD/bin" + PATH="$PATH:$VOLTA_HOME/bin" echo "$PATH" RECORD_INSTALL: sh: if [ -n "$CI" ]; then echo 'true'; fi @@ -430,6 +459,9 @@ env: DSN="$(jq -r '.blueprint.sentryDSN' package.json)" if [ "$DSN" != 'null' ]; then echo "$DSN"; fi fi + VOLTA_HOME: + sh: echo "$HOME/.volta" + profile: | if [[ "$OSTYPE" == 'linux-gnu'* ]] || [[ "$OSTYPE" == 'linux-musl'* ]]; then if [ -f /home/linuxbrew/.linuxbrew/bin/brew ] && ! type brew > /dev/null; then @@ -448,6 +480,7 @@ profile: | if [ -f .venv/bin/activate ]; then . .venv/bin/activate fi + tasks: build: deps: @@ -476,6 +509,7 @@ tasks: else [[ $- == *i* ]] && task prepare || (.config/log error '{{.NONINTERACTIVE_MISSING_BUILD_CMD}}' && exit 1) fi + clean: desc: Removes optional folders that are cached during various tasks summary: | @@ -486,11 +520,13 @@ tasks: which will re-generate the project from scratch. Ideally, this task and the reset task should never be necessary. The `start` task should be used instead. vars: - CLEAN_TARGETS: .autodoc .cache .task .venv node_modules tsconfig.tsbuildinfo venv .variables.json + CLEAN_TARGETS: .autodoc .cache .task .venv node_modules tsconfig.tsbuildinfo venv + .variables.json cmds: - task: common:clean vars: CLEAN_TARGETS: '{{.CLEAN_TARGETS}}' + commit: desc: Lint staged files, report spelling errors, and open a _required_ commit dialoge summary: | @@ -507,6 +543,7 @@ tasks: to your regular `git commit -m` command to bypass the pre-commit hook. cmds: - task: common:commit + commit:all: deps: - install:software:git @@ -544,6 +581,7 @@ tasks: git add --all git commit {{end}} + commit:quick: deps: - ci:commit:config @@ -551,13 +589,16 @@ tasks: - | task --list > /dev/null || (echo "ERROR: Invalid Taskfiles!" && exit 1) git add --all - - "HUSKY=0 git commit -m '\U0001F527 chore(tweak)": quick minor update' --no-verify + - HUSKY=0 git commit -m '🔧 chore(tweak): quick minor update' --no-verify - git push origin master + devcontainer: deps: - install:npm:devcontainer - install:software:docker + donothing: 'true' + fix: desc: Run code auto-fixers / auto-formatters summary: | @@ -568,6 +609,7 @@ tasks: an error so the auto-fixes still have to be validated. cmds: - task: fix:all + fresh: summary: Initialize a new project with only the Taskfile.yml present cmds: @@ -579,6 +621,7 @@ tasks: - TMP="$(mktemp)" && jq -r 'del(.blueprint)' package.json > "$TMP" && mv "$TMP" package.json - bash start.sh - task: prepare + get:links: deps: - install:software:jq @@ -591,6 +634,7 @@ tasks: cmds: - .config/log info 'GitHub -----> `{{.GITHUB_URL}}`' - .config/log info 'GitLab -----> `{{.GITLAB_URL}}`' + group:exec: desc: Execute group commands on any GitLab group (including repositories in sub-groups) summary: | @@ -611,6 +655,7 @@ tasks: Be sure to wrap the command in quotes or you might observe some odd behavior. cmds: - task: git:gitlab:group:exec + init: deps: - install:software:jq @@ -643,10 +688,12 @@ tasks: - git init - task: repair - task: prepare + jumpusb: desc: Creates a JumpUSB (https://jumpusb.com) cmds: - task: install:ventoy + lint: desc: Lints the project using all linters summary: | @@ -660,6 +707,7 @@ tasks: `task lint` cmds: - task: lint:all + livereload: deps: - install:npm:nodemon @@ -699,10 +747,12 @@ tasks: .config/log error '`Taskfile-project.yml` must exist and have a `livereload` task to use with `nodemon`' && exit 1 fi - nodemon --config {{if .CLI_ARGS}}{{.CLI_ARGS}}{{else}}.config/nodemon.json{{end}} + new:project: desc: Create a new project cmds: - task: prepare + preload: desc: Set up your workstation in advance by installing commonly used programs summary: | @@ -745,6 +795,7 @@ tasks: - task: install:pipx:bundle - task: install:python:requirements - task: install:modules:local + prepare: desc: Prepares the project for the normal start command summary: | @@ -761,6 +812,7 @@ tasks: cmds: - task: boilerplate:check:package - task: boilerplate:clean + publish: desc: Publish a semantic release via `semantic-release` summary: | @@ -808,6 +860,7 @@ tasks: success: Successfully ran `semantic-release` via `task publish` cmds: - task: publish:semantic-release + publish:force: desc: Force a `semantic-release` even if there are no new eligible commits summary: | @@ -833,8 +886,10 @@ tasks: start: Publishing `semantic-release` update via `task publish:force` success: Successfully published update via `task publish:force` cmds: - - "HUSKY=0 git commit -a --allow-empty -m '\U0001F528 chore(bump): Forced semantic-release {{.UPDATE_LEVEL}}' -n\n" + - | + HUSKY=0 git commit -a --allow-empty -m '🔨 chore(bump): Forced semantic-release {{.UPDATE_LEVEL}}' -n - task: publish + pull:upstream: desc: Pull from upstream repositories summary: | @@ -851,6 +906,7 @@ tasks: success: Successfully pulled from `upstreamRemotes` cmds: - task: common:update:upstream:remotes:pull + repair: cmds: - task: common:repair @@ -860,6 +916,7 @@ tasks: else bash <(curl -sSL {{.INIT_SCRIPT}}) fi + reset: desc: Resets the project by removing all caches and then re-generating templated files summary: | @@ -871,6 +928,7 @@ tasks: updates, it re-generates any templated files. cmds: - task: common:reset + reset:force: desc: 'Aggressively reset the project (**WARNING** This will wipe uncommitted work)' summary: | @@ -889,6 +947,7 @@ tasks: answer: cmds: - task: common:reset:force + scripts: interactive: true deps: @@ -906,6 +965,7 @@ tasks: start: Running `NTL_RUNNER={{.NPM_PROGRAM}} {{.NPX_HANDLE}}ntl` cmds: - NTL_RUNNER={{.NPM_PROGRAM}} {{.NPX_HANDLE}}ntl + services: desc: Update elements of the repository that require API access summary: | @@ -918,6 +978,7 @@ tasks: - task: common:update:services status: - '[ -n "$GITLAB_CI" ] && [ "$REPOSITORY_UPDATE" != "true" ]' + shell: desc: Start a terminal session using Docker with any Linux operating system compile: | @@ -951,6 +1012,7 @@ tasks: * ubuntu-21.04 cmds: - task: common:shell + start: desc: Start the project by installing / updating dependencies, repairing issues, and opening a tutorial summary: | @@ -974,6 +1036,7 @@ tasks: success: Project started! cmds: - task: common:start + synchronize: desc: Set up the project and refresh it with the latest changes summary: | @@ -994,6 +1057,7 @@ tasks: success: Successfully synchronized the project with upstream file changes and also bootstrapped the project cmds: - task: upstream:{{.PROJECT_TYPE}} + tag:deps: desc: Inject a new command in the `Taskfile.yml` that includes all tasks matching a given tag as deps summary: | @@ -1022,6 +1086,7 @@ tasks: ``` cmds: - task: common:util:task:tag:deps + template: deps: - install:npm:liquidjs @@ -1043,6 +1108,7 @@ tasks: preconditions: - sh: test -f .variables.json msg: This task requires that you have already spun up the project by running `task start` + test: deps: - install:software:jq @@ -1063,6 +1129,7 @@ tasks: else [[ $- == *i* ]] && task prepare || (.config/log error '{{.NONINTERACTIVE_MISSING_TEST_CMD}}' && exit 1) fi + update: desc: Fully update the repository summary: | @@ -1089,7 +1156,9 @@ tasks: cmds: - task: common:start env: - UPDATE_PROJECT: "true" + UPDATE_PROJECT: 'true' + - task: common:update:finish + yubikey: desc: Create an OpenGPG-enabled YubiKey summary: | diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 295384a..6c1c6a8 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -261,6 +261,8 @@ For more informative links, refer to the [GitHub Awesome Guidelines List](https: One way we enforce code style is by including the best standard linters into our projects. We normally keep the settings pretty strict. Although it may seem pointless and annoying at first, these linters will make you a better coder since you will learn to adapt your style to the style of the group of people who spent countless hours creating the linter in the first place. +{{ load:.config/docs/common/contributing/troubleshooting.md }} + ## Contributors diff --git a/package.json b/package.json index e119192..b9cb06b 100644 --- a/package.json +++ b/package.json @@ -48,17 +48,17 @@ }, "optionalDependencies": {}, "devDependencies": { + "@commitlint/config-conventional": "latest", "@types/node": "^16.11.6", "esbuild": "^0.12.29", "esbuild-node-externals": "^1.3.0", "eslint-config-strict-mode": "latest", "git-cz-emoji": "latest", + "handlebars-helpers": "latest", "jest-preset-ts": "latest", "prettier-config-sexy-mode": "latest", "semantic-release-config": "latest", - "typescript": "^4.5.5", - "@commitlint/config-conventional": "latest", - "handlebars-helpers": "latest" + "typescript": "^4.5.5" }, "keywords": [ "common", @@ -114,7 +114,9 @@ "showAuthor": true }, "commitlint": { - "extends": [], + "extends": [ + "@commitlint/config-conventional" + ], "helpUrl": "https://megabyte.space/docs/contributing/commits" }, "eslintConfig": {