Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
114 lines (73 loc) · 2.56 KB

CONTRIBUTING.md

File metadata and controls

114 lines (73 loc) · 2.56 KB

Contributing

This guide is a work in progress, PR's welcome!

TODO

Issues

TODO

Pull-requests

TODO

Development environment

Setting up a local development environment in Linux. Pull-requests welcome for MacOS support. (Although, this is the "Linux Upskill Challenge", why not Linux?)

Python environment

Setting up a local python virtual environment is recommended.

python3 -m venv .env

Install python development environment dependencies.

python3 -m pip install -r requirements-dev.txt

Activate the python environment:

source .env/bin/activate

NodeJS

The markdown linter that's used by this project is an npm package. Install markdown lint dependencies from the package.json file.

npm install

Linting

Linters:

  • yamllint
  • markdownlint
  • ShellCheck
    • Via shellcheck-py. It's easier to manage this project dependency as a pip-installable package. Also, pre-commit uses shellcheck-py because the native ShellCheck pre-commit hook has an annoying Docker dependency.

Pre-commit

If you setup your python development environment by installing pip packages from requirements-dev.txt earlier then pre-commit should already be installed in your python environment.

Pre-commit runs linting, syntax, and other checks via git hook scripts that run before code is committed.

Install pre-commit and the hook scripts defined in .pre-commit-config.yaml:

pre-commit install && pre-commit install-hooks

Pre-commit will now run prior to committing any code with git.

To manually run the hook scripts and lint the repo:

pre-commit
# or run for all files
pre-commit run --all-files

Build

This project uses the MkDocs Python static site generator geared towards building project docs. It uses the mkdocs-material theme.

If you setup your Python environment above, then the mkdocs and mkdocs-material packages should already be installed.

A local instance of the site can be built and served via localhost by running...

mkdocs server

...from the project root directory.

Served from localhost: LUC @localhost

GitHub Actions workflows

Stages:

  • Validate
  • Build & Deploy

TODO: Flesh out this section.