From 9d772383e927ea5ca830d134f5189fd9840afebb Mon Sep 17 00:00:00 2001 From: Nathaniel Young Date: Wed, 29 May 2024 22:40:14 -0700 Subject: [PATCH] style: adds pre-commit checks and formats markdown files (#14) --- .devcontainer/devcontainer.json | 5 ++- .github/PULL_REQUEST_TEMPLATE.md | 4 ++ .github/workflows/code_style.yml | 49 +++++++++++++++++++++ .gitpod.yml | 3 +- .markdownlint.yml | 34 ++++++++++++++ .pre-commit-config.yaml | 21 +++++++++ CONTRIBUTING.md | 26 +++++++++-- Dockerfile | 4 +- README.md | 3 +- docs/ConfigSchema.md | 11 +++-- docs/InstallListSchema.md | 1 + functions/_example/README.md | 1 + functions/add_ohmyzsh_plugins/README.md | 1 + functions/anaconda/README.md | 1 + functions/apk_packages/README.md | 1 + functions/apt_get_packages/README.md | 1 + functions/atom_packages/README.md | 1 + functions/brew_cask_packages/README.md | 1 + functions/brew_packages/README.md | 1 + functions/deb_package/README.md | 1 + functions/git_clone/README.md | 1 + functions/git_config/README.md | 1 + functions/install_ohmyzsh_plugins/README.md | 1 + functions/node_version/README.md | 1 + functions/nvm/README.md | 1 + functions/p10k/install.sh | 6 ++- functions/pacman_packages/README.md | 1 + functions/run_script/README.md | 1 + functions/sdk_candidate/README.md | 1 + functions/snap_package/README.md | 1 + functions/vscode_extensions/README.md | 1 + functions/yum_packages/README.md | 1 + functions/zshenv/README.md | 1 + templates/p10k_config.zsh | 1 - templates/p10k_init.zsh | 1 - 35 files changed, 175 insertions(+), 15 deletions(-) create mode 100644 .github/workflows/code_style.yml create mode 100644 .markdownlint.yml create mode 100644 .pre-commit-config.yaml diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 2f9bb76..28488b5 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -20,9 +20,10 @@ "vscode": { // Add the IDs of extensions you want installed when the container is created. "extensions": [ - "tamasfe.even-better-toml", "dart-code.dart-code", - "editorconfig.editorconfig" + "DavidAnson.vscode-markdownlint", + "editorconfig.editorconfig", + "tamasfe.even-better-toml" ] } }, diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a0a6595..30e5b1f 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,3 +1,7 @@ +--- +# adds title in frontmatter so it does not fail style check +title: 'Pull Request Template' +--- ## Description diff --git a/.github/workflows/code_style.yml b/.github/workflows/code_style.yml new file mode 100644 index 0000000..c182e98 --- /dev/null +++ b/.github/workflows/code_style.yml @@ -0,0 +1,49 @@ +name: Code Style + +on: + push: + branches: + - main + pull_request: + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name }} + cancel-in-progress: true + +jobs: + code-style-checks: + name: Code Style Checks + runs-on: ubuntu-latest + timeout-minutes: 15 + + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Get exact Python version + run: echo "python_version=$(python --version)" >> $GITHUB_ENV + + - name: Cache Virtual Environment and pre-commit cache + uses: actions/cache@v4 + id: cache-pre-commit + with: + path: | + venv + pre-commit-cache + key: v1-venv-pre-commit-${{ runner.os }}-${{ env.python_version }}-${{ hashFiles('.pre-commit-config.yaml') }} + + - name: Install pre-commit + if: steps.cache-pre-commit.outputs.cache-hit != 'true' + run: | + python -m venv venv + source venv/bin/activate + pip install pre-commit + + - name: Run Style Check + run: | + source venv/bin/activate + PRE_COMMIT_HOME="$PWD/pre-commit-cache" pre-commit run --all-files --color always --verbose --hook-stage manual diff --git a/.gitpod.yml b/.gitpod.yml index 5869aea..583a3c2 100644 --- a/.gitpod.yml +++ b/.gitpod.yml @@ -7,6 +7,7 @@ tasks: vscode: extensions: - - tamasfe.even-better-toml - dart-code.dart-code + - DavidAnson.vscode-markdownlint - editorconfig.editorconfig + - tamasfe.even-better-toml diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000..768d050 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,34 @@ +# documentation: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md + +# unordered list style +MD004: + style: dash + +# maximum line length +# disable it +MD013: false + +# multiple headings with the same context +MD024: + # duplication is allowed for headings with different parents + siblings_only: true + +# code block style +MD046: + style: fenced + +# code fence style +MD048: + style: backtick + +# emphasis style +MD049: + style: asterisk + +# strong style +MD050: + style: asterisk + +# table pipe style +MD055: + style: leading_and_trailing diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..f55c20d --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,21 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: end-of-file-fixer + - id: mixed-line-ending + args: [--fix=lf] + - id: trailing-whitespace + - id: check-shebang-scripts-are-executable + + - repo: https://github.com/DavidAnson/markdownlint-cli2 + rev: v0.13.0 + hooks: + # manual stage for running in the ci so that it will print out the errors + - id: markdownlint-cli2 + name: Run markdownlint and log errors + stages: [manual] + + - id: markdownlint-cli2 + name: Run markdownlint and fix errors + args: [--fix] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 68a3a8d..dddd307 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ If you have a suggestion, take a look at the existing issues and if you find a s ### Getting Started -If you have a bug fix, performance improvement, feature addition, documentation imrpovement, etc. that could be useful for this respository, I would be happy to have your have your contribution. First, make sure that there does not already exist a similar pending pull request. To create a pull request, please create a fork of this repo on GitHub. +If you have a bug fix, performance improvement, feature addition, documentation improvement, etc. that could be useful for this respository, I would be happy to have your have your contribution. First, make sure that there does not already exist a similar pending pull request. To create a pull request, please create a fork of this repo on GitHub. ### Coding @@ -28,7 +28,7 @@ If you have a bug fix, performance improvement, feature addition, documentation It does not really matter what editor you use; however, if you want to contribute to the Dart codebase and do not want to set up Dart on your local machine, you can use a containerized development environment with all of the requirements built-in. Here are two options: -1. Gitpod. This repo has a Gitpod config already setup, so all you have to do is visit: https://gitpod.io/#https://github.com/nyoungstudios/alfa. Or replace my GitHub url with your fork. +1. Gitpod. This repo has a Gitpod config already setup, so all you have to do is visit: . Or replace my GitHub url with your fork. 2. VS Code's dev container. In order to use this, clone your fork to your local machine and follow this [setup guide](https://code.visualstudio.com/docs/remote/containers) before opening the folder in VS Code. In short, you will need to install Docker and the [VS Code Remote Containers extension](https://aka.ms/vscode-remote/download/containers). Finally, when opening the repo in VS Code, it will prompt you to open it in the dev container. Then, it will build the Docker image with all the dependencies needed. To build the Dart executable, just run `make` from the repository's root directory. It will build and appropriately rename the executable to what the `install.sh` script expects. @@ -39,7 +39,27 @@ If you like to contribute a new entry with a function to install something, you ### Style -This respository uses EditorConfig to define the number of spaces for indentation as well as removing excess white characters. If your editor does not come bundled with native support, you can install the appropriate EditorConfig extension. For more information, please visit their [website](https://editorconfig.org). Additionally, if you are contributing to the Dart codebase, this repo includes a VS Code `settings.json` file with the recommended Dart editor guidelines in addiiton to the Dart linting rules defined in `analysis_options.yaml`. To run the Dart linter, you can run `dart analyze` (or `make lint`). And to apply the automated linting changes, run `dart fix --apply` (or `make fix`). +It is important to maintain consistent coding style. This repository uses GitHub Action checks to validate that all code contributions pass the style checks. Part of the style checks are validated with [pre-commit](https://pre-commit.com). You do not need to install pre-commit locally when developing as it should be easy enough to identify the style problems by using the appropriate IDE extensions. The pre-commit checks do automatically fix a handful of style related problems, so here is how to run them locally if you like. + +```bash +# install pre-commit +pip install pre-commit + +# run the checks +pre-commit run --all-files +``` + +#### General + +This respository uses EditorConfig to define the number of spaces for indentation as well as removing excess white characters. If your editor does not come bundled with native support, you can install the appropriate EditorConfig extension. For more information, please visit their [website](https://editorconfig.org). + +#### Markdown + +This repository uses [markdownlint](https://github.com/DavidAnson/markdownlint) to standardize the formatting of Markdown files. If you are using VS Code, you can install the [extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) so that warning messages will appear when something does not follow the standard. + +#### Dart + +Additionally, if you are contributing to the Dart codebase, this repo includes a VS Code `settings.json` file with the recommended Dart editor guidelines in addiiton to the Dart linting rules defined in `analysis_options.yaml`. To run the Dart linter, you can run `dart analyze` (or `make lint`). And to apply the automated linting changes, run `dart fix --apply` (or `make fix`). ### Testing diff --git a/Dockerfile b/Dockerfile index 6555996..c78fc39 100644 --- a/Dockerfile +++ b/Dockerfile @@ -15,7 +15,7 @@ ARG MIN="no" RUN if [ "$MIN" = "no" ]; then \ git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k && \ - sed -i '1 e cat /tmp/templates/p10k_init.zsh && cat /tmp/templates/zshrc_disable_flag.zsh' ~/.zshrc && \ + sed -i '1 e cat /tmp/templates/p10k_init.zsh && echo && cat /tmp/templates/zshrc_disable_flag.zsh' ~/.zshrc && \ sed -i 's+ZSH_THEME="robbyrussell"+ZSH_THEME="powerlevel10k/powerlevel10k"+g' ~/.zshrc; \ else \ sed -i '1 e cat /tmp/templates/zshrc_disable_flag.zsh' ~/.zshrc; \ @@ -32,8 +32,10 @@ RUN if [ "$MIN" = "no" ]; then \ fi && \ echo "" >> ~/.bashrc && \ cat /tmp/templates/gitpod_env.zsh >> ~/.bashrc && \ + echo "" >> ~/.bashrc && \ echo "" >> ~/.zshrc && \ cat /tmp/templates/gitpod_env.zsh >> ~/.zshrc && \ + echo "" >> ~/.zshrc && \ rm -rf /tmp/templates ENV SHELL='/bin/zsh' diff --git a/README.md b/README.md index 86f9a0a..e315de2 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ 📋 Alfa is tool to manage and share your dev environment configuration. It's modular approach allows you to easily group different configurations together. The goal was to create a way to install all of your favorite tools whether you are running on an x86 or ARM architecture computer for both on macOS and Linux operating systems. -✈️ As a flight sim enthusiast, _Alfa_ is named after the first word in the NATO phonetic alphabet. While getting a new computer is always exciting, setting it up with all your tools and settings can be a little tedious. I hope this will help simplify your preflight steps so that you can focus on the flying part. +✈️ As a flight sim enthusiast, *Alfa* is named after the first word in the NATO phonetic alphabet. While getting a new computer is always exciting, setting it up with all your tools and settings can be a little tedious. I hope this will help simplify your preflight steps so that you can focus on the flying part. ## Prerequisites @@ -21,6 +21,7 @@ cd alfa ``` This is the installer script (more on how to use it below): + ```shell ./install.sh -h ``` diff --git a/docs/ConfigSchema.md b/docs/ConfigSchema.md index df1a4b0..7ef06a6 100644 --- a/docs/ConfigSchema.md +++ b/docs/ConfigSchema.md @@ -78,6 +78,7 @@ echo_stuff() { ``` And we set the options as: + ```toml options = [ "hi", @@ -86,7 +87,8 @@ options = [ ``` It will print this to standard out: -``` + +```text hi user ``` @@ -102,16 +104,19 @@ echo_stuff() { ``` And we set the env as: + ```toml env = { NAME = "joe" } ``` It will print this to standard out: -``` + +```text joe ``` However, if we do not set the env, it will print this to standard out: -``` + +```text user ``` diff --git a/docs/InstallListSchema.md b/docs/InstallListSchema.md index 7df0ed0..19335bf 100644 --- a/docs/InstallListSchema.md +++ b/docs/InstallListSchema.md @@ -32,6 +32,7 @@ custom ``` And in this case, only these items would be installed: + ```txt name item1 diff --git a/functions/_example/README.md b/functions/_example/README.md index 94b1c16..22b29eb 100644 --- a/functions/_example/README.md +++ b/functions/_example/README.md @@ -9,6 +9,7 @@ This is a example function for demostration purposes. ## Options Accepts any number of arguments. + - each argument is a printed to stdout ## Example diff --git a/functions/add_ohmyzsh_plugins/README.md b/functions/add_ohmyzsh_plugins/README.md index 664b608..5a5f9b0 100644 --- a/functions/add_ohmyzsh_plugins/README.md +++ b/functions/add_ohmyzsh_plugins/README.md @@ -9,6 +9,7 @@ Modifies your `.zshrc` file to define which Oh My Zsh plugins to load. ## Options Accepts any number of arguments. + - each argument is the plugin name. They can either be built-in plugins or custom plugins ## Example diff --git a/functions/anaconda/README.md b/functions/anaconda/README.md index 6835d17..92e9826 100644 --- a/functions/anaconda/README.md +++ b/functions/anaconda/README.md @@ -9,6 +9,7 @@ Installs Anaconda 3. ## Options Accepts 0 or 1 arguments. + - argument 1 is the url to download the anaconda installer. If not specified explicitly, it will default to the latest installer for the respective operating system and architecture that it is running on ## Environment Variables diff --git a/functions/apk_packages/README.md b/functions/apk_packages/README.md index 4249136..c3d728a 100644 --- a/functions/apk_packages/README.md +++ b/functions/apk_packages/README.md @@ -9,6 +9,7 @@ Installs apk packages. ## Options Accepts any number of arguments. + - all arguments are passed after the `apk add --no-interactive` command ## Example diff --git a/functions/apt_get_packages/README.md b/functions/apt_get_packages/README.md index 53817f6..08ae540 100644 --- a/functions/apt_get_packages/README.md +++ b/functions/apt_get_packages/README.md @@ -9,6 +9,7 @@ Installs apt-get packages. ## Options Accepts any number of arguments. + - all arguments are passed after the `apt-get install -y` command ## Example diff --git a/functions/atom_packages/README.md b/functions/atom_packages/README.md index a630248..eb2827e 100644 --- a/functions/atom_packages/README.md +++ b/functions/atom_packages/README.md @@ -9,6 +9,7 @@ Installs atom packages. ## Options Accepts any number of arguments. + - each argument is an atom package to install ## Example diff --git a/functions/brew_cask_packages/README.md b/functions/brew_cask_packages/README.md index 84e2ac6..62ad231 100644 --- a/functions/brew_cask_packages/README.md +++ b/functions/brew_cask_packages/README.md @@ -9,6 +9,7 @@ Installs brew cask packages. ## Options Accepts any number of arguments. + - each argument is a brew cask package to install ## Example diff --git a/functions/brew_packages/README.md b/functions/brew_packages/README.md index dfccbb1..7d2da7e 100644 --- a/functions/brew_packages/README.md +++ b/functions/brew_packages/README.md @@ -9,6 +9,7 @@ Installs brew packages. ## Options Accepts any number of arguments. + - each argument is a brew package to install ## Example diff --git a/functions/deb_package/README.md b/functions/deb_package/README.md index 706bc0f..3527dd5 100644 --- a/functions/deb_package/README.md +++ b/functions/deb_package/README.md @@ -9,6 +9,7 @@ Installs a single deb package. ## Options Accepts exactly 1 argument. + - argument 1 is the url to download the deb file ## Example diff --git a/functions/git_clone/README.md b/functions/git_clone/README.md index 5fc9f7a..2d4a320 100644 --- a/functions/git_clone/README.md +++ b/functions/git_clone/README.md @@ -9,6 +9,7 @@ Clones any number of git repos to a specified parent folder. Will create the fol ## Options Accepts any number of arguments. + - argument 1 is file path to the folder - each argument afterwards is the git url to clone diff --git a/functions/git_config/README.md b/functions/git_config/README.md index 0651329..e4d6c24 100644 --- a/functions/git_config/README.md +++ b/functions/git_config/README.md @@ -9,6 +9,7 @@ Sets the git user name and git user email attributes. And creates a ssh key whic ## Options Accepts exactly 2 arguments + - argument 1 is the git user name - argument 2 is the git user email diff --git a/functions/install_ohmyzsh_plugins/README.md b/functions/install_ohmyzsh_plugins/README.md index 5808d96..60ca79f 100644 --- a/functions/install_ohmyzsh_plugins/README.md +++ b/functions/install_ohmyzsh_plugins/README.md @@ -9,6 +9,7 @@ Downloads Oh My Zsh plugins and saves them to your Oh My Zsh custom plugins fold ## Options Accepts any number of arguments. + - each argument is a git url to clone the Oh My Zsh plugin from ## Example diff --git a/functions/node_version/README.md b/functions/node_version/README.md index 1ae49cb..3b00319 100644 --- a/functions/node_version/README.md +++ b/functions/node_version/README.md @@ -9,6 +9,7 @@ Installs the latest Node version with NVM. Or can explicitly specify which Node ## Options Accepts 0 or 1 arguments. + - If argument 1 is given, then it will explicitly install the given Node version. Otherwise, it will install the latest Node version ## Example diff --git a/functions/nvm/README.md b/functions/nvm/README.md index 1d68907..7ad0c31 100644 --- a/functions/nvm/README.md +++ b/functions/nvm/README.md @@ -9,6 +9,7 @@ Installs NVM (Node Version Manager). ## Options Accepts 0 or 1 arguments. + - If argument 1 is equal to "0", then it will not modify your profile or rc file. Otherwise, it will try to guess which profile or rc file you are using ## Example diff --git a/functions/p10k/install.sh b/functions/p10k/install.sh index 559a0ab..87fedbe 100755 --- a/functions/p10k/install.sh +++ b/functions/p10k/install.sh @@ -8,9 +8,10 @@ prettify_terminal_macos() { # edit the .zshrc echo "Changing .zshrc file to Powerlevel10k theme" - cat ~/.zshrc | pbcopy && cat templates/p10k_init.zsh templates/zshrc_disable_flag.zsh > ~/.zshrc && pbpaste >> ~/.zshrc + cat ~/.zshrc | pbcopy && cat templates/p10k_init.zsh <(echo) templates/zshrc_disable_flag.zsh > ~/.zshrc && pbpaste >> ~/.zshrc echo "" >> ~/.zshrc cat templates/p10k_config.zsh >> ~/.zshrc + echo "" >> ~/.zshrc # replaces the default theme with the p10k theme sed -i '.old' 's+^ZSH_THEME=".*"$+ZSH_THEME="powerlevel10k/powerlevel10k"+g' ~/.zshrc @@ -25,9 +26,10 @@ prettify_terminal_linux() { # edit the .zshrc echo "Changing .zshrc file to Powerlevel10k theme" - sed -i '1 e cat templates/p10k_init.zsh && cat templates/zshrc_disable_flag.zsh' ~/.zshrc + sed -i '1 e cat templates/p10k_init.zsh && echo && cat templates/zshrc_disable_flag.zsh' ~/.zshrc echo "" >> ~/.zshrc cat templates/p10k_config.zsh >> ~/.zshrc + echo "" >> ~/.zshrc # replaces the default theme with the p10k theme sed -i 's+^ZSH_THEME=".*"$+ZSH_THEME="powerlevel10k/powerlevel10k"+g' ~/.zshrc diff --git a/functions/pacman_packages/README.md b/functions/pacman_packages/README.md index 0948d72..08732fc 100644 --- a/functions/pacman_packages/README.md +++ b/functions/pacman_packages/README.md @@ -9,6 +9,7 @@ Installs pacman packages. ## Options Accepts any number of arguments. + - all arguments are passed after the `pacman -Sy --noconfirm` command ## Example diff --git a/functions/run_script/README.md b/functions/run_script/README.md index 7f9059d..c8532da 100644 --- a/functions/run_script/README.md +++ b/functions/run_script/README.md @@ -9,6 +9,7 @@ Clones a git repo to a specified parent folder, and it will create the folder if ## Options Accepts any number of arguments. + - argument 1 is the file path to the folder - argument 2 is the git url to clone - each argument afterwards is a command/script to be run diff --git a/functions/sdk_candidate/README.md b/functions/sdk_candidate/README.md index 42daedf..b81c8d3 100644 --- a/functions/sdk_candidate/README.md +++ b/functions/sdk_candidate/README.md @@ -9,6 +9,7 @@ Installs a single candidate with SDKMAN. ## Options Accepts any number of arguments. + - all arguments are passed after the `sdk install` command ## Example diff --git a/functions/snap_package/README.md b/functions/snap_package/README.md index ed102c7..56b5959 100644 --- a/functions/snap_package/README.md +++ b/functions/snap_package/README.md @@ -9,6 +9,7 @@ Installs a single snap package. ## Options Accepts any number of arguments. + - all arguments are passed after the `snap install` command ## Example diff --git a/functions/vscode_extensions/README.md b/functions/vscode_extensions/README.md index 5d9729c..7f85d17 100644 --- a/functions/vscode_extensions/README.md +++ b/functions/vscode_extensions/README.md @@ -9,6 +9,7 @@ Installs Visual Studio Code extensions. ## Options Accepts any number of arguments. + - each argument is a Visual Studio Code extension to install ## Example diff --git a/functions/yum_packages/README.md b/functions/yum_packages/README.md index 0eea697..3d37bef 100644 --- a/functions/yum_packages/README.md +++ b/functions/yum_packages/README.md @@ -9,6 +9,7 @@ Installs yum packages. ## Options Accepts any number of arguments. + - all arguments are passed after the `yum install -y` command ## Example diff --git a/functions/zshenv/README.md b/functions/zshenv/README.md index 06ad01f..70a84ee 100644 --- a/functions/zshenv/README.md +++ b/functions/zshenv/README.md @@ -9,6 +9,7 @@ Appends lines to your `.zshenv` file. ## Options Accepts any number of arguments. + - each argument is a line in your `.zshenv` file ## Example diff --git a/templates/p10k_config.zsh b/templates/p10k_config.zsh index 40bd6c2..a61cad9 100644 --- a/templates/p10k_config.zsh +++ b/templates/p10k_config.zsh @@ -1,3 +1,2 @@ # To customize prompt, run `p10k configure` or edit ~/.p10k.zsh. [[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh - diff --git a/templates/p10k_init.zsh b/templates/p10k_init.zsh index 16b4bbf..d657c48 100644 --- a/templates/p10k_init.zsh +++ b/templates/p10k_init.zsh @@ -4,4 +4,3 @@ if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" fi -