From 72b24b951b10d146b0495221cebd1010e241d4e8 Mon Sep 17 00:00:00 2001 From: Tim Paine <3105306+timkpaine@users.noreply.github.com> Date: Tue, 29 Jul 2025 14:28:27 -0400 Subject: [PATCH] Add wiki support, add separate docs linting, add vscode folder for js --- copier.yaml | 5 + ...% if add_wiki %}wiki.yaml{% endif %}.jinja | 27 ++++ cpp/Makefile.jinja | 12 +- cpp/README.md.jinja | 1 - cpp/pyproject.toml.jinja | 4 + .../wiki/_Footer.md.jinja | 1 + .../wiki/_Sidebar.md.jinja | 16 +++ .../contribute/Build-from-Source.md.jinja | 103 ++++++++++++++ .../wiki/contribute/Contribute.md.jinja | 15 ++ .../Local-Development-Setup.md.jinja | 55 ++++++++ examples/cpp.yaml | 1 + examples/js.yaml | 1 + examples/jupyter.yaml | 1 + examples/python.yaml | 1 + examples/rust.yaml | 1 + ...% if add_wiki %}wiki.yaml{% endif %}.jinja | 27 ++++ js/.vscode/settings.json | 3 + js/Makefile.jinja | 14 +- js/README.md.jinja | 1 - js/pyproject.toml.jinja | 5 + .../wiki/_Footer.md.jinja | 1 + .../wiki/_Sidebar.md.jinja | 16 +++ .../contribute/Build-from-Source.md.jinja | 131 ++++++++++++++++++ .../wiki/contribute/Contribute.md.jinja | 15 ++ .../Local-Development-Setup.md.jinja | 55 ++++++++ ...% if add_wiki %}wiki.yaml{% endif %}.jinja | 27 ++++ jupyter/.vscode/settings.json | 3 + jupyter/Makefile.jinja | 16 ++- jupyter/README.md.jinja | 1 - jupyter/pyproject.toml.jinja | 5 + .../wiki/_Footer.md.jinja | 1 + .../wiki/_Sidebar.md.jinja | 16 +++ .../contribute/Build-from-Source.md.jinja | 131 ++++++++++++++++++ .../wiki/contribute/Contribute.md.jinja | 15 ++ .../Local-Development-Setup.md.jinja | 55 ++++++++ ...% if add_wiki %}wiki.yaml{% endif %}.jinja | 27 ++++ python/Makefile.jinja | 19 ++- python/README.md.jinja | 1 - python/pyproject.toml.jinja | 4 + .../wiki/_Footer.md.jinja | 1 + .../wiki/_Sidebar.md.jinja | 16 +++ .../contribute/Build-from-Source.md.jinja | 103 ++++++++++++++ .../wiki/contribute/Contribute.md.jinja | 15 ++ .../Local-Development-Setup.md.jinja | 55 ++++++++ rust/.github/workflows/build.yaml.jinja | 2 +- ...% if add_wiki %}wiki.yaml{% endif %}.jinja | 27 ++++ rust/Makefile.jinja | 50 ++++--- rust/README.md.jinja | 1 - rust/pyproject.toml.jinja | 4 + .../wiki/_Footer.md.jinja | 1 + .../wiki/_Sidebar.md.jinja | 16 +++ .../contribute/Build-from-Source.md.jinja | 127 +++++++++++++++++ .../wiki/contribute/Contribute.md.jinja | 15 ++ .../Local-Development-Setup.md.jinja | 55 ++++++++ 54 files changed, 1279 insertions(+), 42 deletions(-) create mode 100644 cpp/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja create mode 100644 cpp/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja create mode 100644 cpp/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja create mode 100644 cpp/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja create mode 100644 cpp/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja create mode 100644 cpp/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja create mode 100644 js/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja create mode 100644 js/.vscode/settings.json create mode 100644 js/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja create mode 100644 js/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja create mode 100644 js/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja create mode 100644 js/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja create mode 100644 js/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja create mode 100644 jupyter/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja create mode 100644 jupyter/.vscode/settings.json create mode 100644 jupyter/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja create mode 100644 jupyter/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja create mode 100644 jupyter/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja create mode 100644 jupyter/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja create mode 100644 jupyter/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja create mode 100644 python/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja create mode 100644 python/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja create mode 100644 python/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja create mode 100644 python/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja create mode 100644 python/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja create mode 100644 python/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja create mode 100644 rust/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja create mode 100644 rust/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja create mode 100644 rust/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja create mode 100644 rust/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja create mode 100644 rust/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja create mode 100644 rust/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja diff --git a/copier.yaml b/copier.yaml index 533e20f..e283944 100644 --- a/copier.yaml +++ b/copier.yaml @@ -70,3 +70,8 @@ add_docs: type: bool default: false help: Add documentation using Yardang/Sphinx + +add_wiki: + type: bool + default: false + help: Add documentation using GitHub wiki diff --git a/cpp/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja b/cpp/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja new file mode 100644 index 0000000..1588acd --- /dev/null +++ b/cpp/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja @@ -0,0 +1,27 @@ +name: Publish Docs + +on: + push: + branches: + - main + paths: + - "docs/**" + - "README.md" + workflow_dispatch: + +concurrency: + group: docs + cancel-in-progress: true + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: cp README.md docs/wiki/Home.md + - uses: Andrew-Chen-Wang/github-wiki-action@v4 + with: + path: docs/wiki diff --git a/cpp/Makefile.jinja b/cpp/Makefile.jinja index cfaa521..37ec244 100644 --- a/cpp/Makefile.jinja +++ b/cpp/Makefile.jinja @@ -24,7 +24,7 @@ install: ## install python library ######### # LINTS # ######### -.PHONY: lint-py lint-cpp lint lints +.PHONY: lint-py lint-cpp lint-docs lint lints lint-py: ## run python linter with ruff python -m ruff check {{module}} python -m ruff format --check {{module}} @@ -32,6 +32,10 @@ lint-py: ## run python linter with ruff lint-cpp: ## run cpp linter clang-format --dry-run -Werror -i -style=file `find ./cpp -name "*.*pp"` +lint-docs: ## lint docs with mdformat and codespell + python -m mdformat --check README.md {% if add_wiki %}docs/wiki/{% endif %} + python -m codespell_lib README.md {% if add_wiki %}docs/wiki/{% endif %} + lint: lint-cpp lint-py ## run project linters # alias @@ -45,7 +49,11 @@ fix-py: ## fix python formatting with ruff fix-cpp: ## fix cpp formatting clang-format -i -style=file `find ./cpp -name "*.*pp"` -fix: fix-cpp fix-py ## run project autoformatters +fix-docs: ## autoformat docs with mdformat and codespell + python -m mdformat README.md {% if add_wiki %}docs/wiki/{% endif %} + python -m codespell_lib --write README.md {% if add_wiki %}docs/wiki/{% endif %} + +fix: fix-cpp fix-py fix-docs ## run project autoformatters # alias format: fix diff --git a/cpp/README.md.jinja b/cpp/README.md.jinja index ee722e1..d8ce83b 100644 --- a/cpp/README.md.jinja +++ b/cpp/README.md.jinja @@ -9,6 +9,5 @@ ## Overview - > [!NOTE] > This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base). diff --git a/cpp/pyproject.toml.jinja b/cpp/pyproject.toml.jinja index 12b74af..dac9ded 100644 --- a/cpp/pyproject.toml.jinja +++ b/cpp/pyproject.toml.jinja @@ -37,8 +37,11 @@ develop = [ "bump-my-version", "check-manifest", "cibuildwheel", + "codespell>=2.4,<2.5", "hatch-cpp", "hatchling", + "mdformat>=0.7.22,<0.8", + "mdformat-tables>=1", "pytest", "pytest-cov", "ruff", @@ -56,6 +59,7 @@ Homepage = "https://github.com/{{github}}/{{project_name_formatted}}" current_version = "0.1.0" commit = true tag = true +commit_args = "-s" [[tool.bumpversion.files]] filename = "{{module}}/__init__.py" diff --git a/cpp/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja b/cpp/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja new file mode 100644 index 0000000..4a5fb4b --- /dev/null +++ b/cpp/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja @@ -0,0 +1 @@ +_This wiki is autogenerated. To made updates, open a PR against the original source file in [`docs/wiki`](https://github.com/{{github}}/{{project_name_formatted}}/tree/main/docs/wiki)._ diff --git a/cpp/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja b/cpp/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja new file mode 100644 index 0000000..988b1ac --- /dev/null +++ b/cpp/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja @@ -0,0 +1,16 @@ + + +**[Home](Home)** + +**Get Started** + +- [Installation](Installation) +- [Contributing](Contribute) +- [Development Setup](Local-Development-Setup) +- [Build from Source](Build-from-Source) diff --git a/cpp/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja b/cpp/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja new file mode 100644 index 0000000..ff2651e --- /dev/null +++ b/cpp/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja @@ -0,0 +1,103 @@ +`{{project_name_formatted}}` is written in Python. While prebuilt wheels are provided for end users, it is also straightforward to build `{{project_name_formatted}}` from either the Python [source distribution](https://packaging.python.org/en/latest/specifications/source-distribution-format/) or the GitHub repository. + +- [Make commands](#make-commands) +- [Prerequisites](#prerequisites) +- [Clone](#clone) +- [Install Python dependencies](#install-python-dependencies) +- [Build](#build) +- [Lint and Autoformat](#lint-and-autoformat) +- [Testing](#testing) + +## Make commands + +As a convenience, `{{project_name_formatted}}` uses a `Makefile` for commonly used commands. You can print the main available commands by running `make` with no arguments + +```bash +> make + +build build the library +clean clean the repository +fix run autofixers +install install library +lint run lints +test run the tests +``` + +## Prerequisites + +`{{project_name_formatted}}` has a few system-level dependencies which you can install from your machine package manager. Other package managers like `conda`, `nix`, etc, should also work fine. + +## Clone + +Clone the repo with: + +```bash +git clone https://github.com/{{github}}/{{project_name_formatted}}.git +cd {{project_name_formatted}} +``` + +## Install Python dependencies + +Python build and develop dependencies are specified in the `pyproject.toml`, but you can manually install them: + +```bash +make requirements +``` + +Note that these dependencies would otherwise be installed normally as part of [PEP517](https://peps.python.org/pep-0517/) / [PEP518](https://peps.python.org/pep-0518/). + +## Build + +Build the python project in the usual manner: + +```bash +make build +``` + +## Lint and Autoformat + +`{{project_name_formatted}}` has linting and auto formatting. + +| Language | Linter | Autoformatter | Description | +| :------- | :---------- | :------------ | :---------- | +| Python | `ruff` | `ruff` | Style | +| Markdown | `mdformat` | `mdformat` | Style | +| Markdown | `codespell` | | Spelling | + +**Python Linting** + +```bash +make lint-py +``` + +**Python Autoformatting** + +```bash +make fix-py +``` + +**Documentation Linting** + +```bash +make lint-docs +``` + +**Documentation Autoformatting** + +```bash +make fix-docs +``` + +## Testing + +`{{project_name_formatted}}` has extensive Python tests. The tests can be run via `pytest`. First, install the Python development dependencies with + +```bash +make develop +``` + +**Python** + +```bash +make test +``` diff --git a/cpp/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja b/cpp/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja new file mode 100644 index 0000000..7deea95 --- /dev/null +++ b/cpp/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja @@ -0,0 +1,15 @@ +Contributions are welcome on this project. We distribute under the terms of the [Apache 2.0 license](https://github.com/{{github}}/{{project_name_formatted}}/blob/main/LICENSE). + +> [!NOTE] +> +> `{{project_name_formatted}}` requires [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions. +> This is enforced by a [Probot GitHub App](https://probot.github.io/apps/dco/), which checks that commits are "signed". +> Read [instructions to configure commit signing](Local-Development-Setup#configure-commit-signing). + +For **bug reports** or **small feature requests**, please open an issue on our [issues page](https://github.com/{{github}}/{{project_name_formatted}}/issues). + +For **questions** or to discuss **larger changes or features**, please use our [discussions page](https://github.com/{{github}}/{{project_name_formatted}}/discussions). + +For **contributions**, please see our [developer documentation](Local-Development-Setup). We have `help wanted` and `good first issue` tags on our issues page, so these are a great place to start. + +For **documentation updates**, make PRs that update the pages in `/docs/wiki`. The documentation is pushed to the GitHub wiki automatically through a GitHub workflow. Note that direct updates to this wiki will be overwritten. diff --git a/cpp/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja b/cpp/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja new file mode 100644 index 0000000..897872a --- /dev/null +++ b/cpp/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja @@ -0,0 +1,55 @@ +## Table of Contents + +- [Table of Contents](#table-of-contents) +- [Step 1: Build from Source](#step-1-build-from-source) +- [Step 2: Configuring Git and GitHub for Development](#step-2-configuring-git-and-github-for-development) + - [Create your fork](#create-your-fork) + - [Configure remotes](#configure-remotes) + - [Authenticating with GitHub](#authenticating-with-github) +- [Guidelines](#guidelines) + +## Step 1: Build from Source + +To work on `{{project_name_formatted}}`, you are going to need to build it from source. See +[Build from Source](Build-from-Source) for +detailed build instructions. + +Once you've built `{{project_name_formatted}}` from a `git` clone, you will also need to +configure `git` and your GitHub account for `{{project_name_formatted}}` development. + +## Step 2: Configuring Git and GitHub for Development + +### Create your fork + +The first step is to create a personal fork of `{{project_name_formatted}}`. To do so, click +the "fork" button at https://github.com/{{github}}/{{project_name_formatted}}, or just navigate +[here](https://github.com/{{github}}/{{project_name_formatted}}/fork) in your browser. Set the +owner of the repository to your personal GitHub account if it is not +already set that way and click "Create fork". + +### Configure remotes + +Next, you should set some names for the `git` remotes corresponding to +main {{github}} repository and your fork. See the [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork) for more information. + +### Authenticating with GitHub + +If you have not already configured `ssh` access to GitHub, you can find +instructions to do so +[here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh), +including instructions to create an SSH key if you have not done +so. Authenticating with SSH is usually the easiest route. If you are working in +an environment that does not allow SSH connections to GitHub, you can look into +[configuring a hardware +passkey](https://docs.github.com/en/authentication/authenticating-with-a-passkey/about-passkeys) +or adding a [personal access +token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) +to avoid the need to type in your password every time you push to your fork. + +## Guidelines + +After developing a change locally, ensure that both [lints](Build-from-Source#lint-and-autoformat) and [tests](Build-from-Source#testing) pass. Commits should be squashed into logical units, and all commits must be signed (e.g. with the `-s` git flag). We require [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions. + +If your work is still in-progress, open a [draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests). Otherwise, open a normal pull request. It might take a few days for a maintainer to review and provide feedback, so please be patient. If a maintainer asks for changes, please make said changes and squash your commits if necessary. If everything looks good to go, a maintainer will approve and merge your changes for inclusion in the next release. + +Please note that non substantive changes, large changes without prior discussion, etc, are not accepted and pull requests may be closed. diff --git a/examples/cpp.yaml b/examples/cpp.yaml index 17bc99d..62853fc 100644 --- a/examples/cpp.yaml +++ b/examples/cpp.yaml @@ -1,5 +1,6 @@ --- add_docs: true +add_wiki: true add_extension: cpp email: 3105306+timkpaine@users.noreply.github.com github: python-project-templates diff --git a/examples/js.yaml b/examples/js.yaml index a114e9b..291dfde 100644 --- a/examples/js.yaml +++ b/examples/js.yaml @@ -1,5 +1,6 @@ --- add_docs: true +add_wiki: true add_extension: js email: 3105306+timkpaine@users.noreply.github.com github: python-project-templates diff --git a/examples/jupyter.yaml b/examples/jupyter.yaml index 336fd07..8049295 100644 --- a/examples/jupyter.yaml +++ b/examples/jupyter.yaml @@ -1,5 +1,6 @@ --- add_docs: true +add_wiki: true add_extension: jupyter email: 3105306+timkpaine@users.noreply.github.com github: python-project-templates diff --git a/examples/python.yaml b/examples/python.yaml index 8110b09..7aacf79 100644 --- a/examples/python.yaml +++ b/examples/python.yaml @@ -1,5 +1,6 @@ --- add_docs: true +add_wiki: true add_extension: python email: 3105306+timkpaine@users.noreply.github.com github: python-project-templates diff --git a/examples/rust.yaml b/examples/rust.yaml index a19c71d..cff2804 100644 --- a/examples/rust.yaml +++ b/examples/rust.yaml @@ -1,5 +1,6 @@ --- add_docs: true +add_wiki: true add_extension: rust email: 3105306+timkpaine@users.noreply.github.com github: python-project-templates diff --git a/js/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja b/js/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja new file mode 100644 index 0000000..1588acd --- /dev/null +++ b/js/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja @@ -0,0 +1,27 @@ +name: Publish Docs + +on: + push: + branches: + - main + paths: + - "docs/**" + - "README.md" + workflow_dispatch: + +concurrency: + group: docs + cancel-in-progress: true + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: cp README.md docs/wiki/Home.md + - uses: Andrew-Chen-Wang/github-wiki-action@v4 + with: + path: docs/wiki diff --git a/js/.vscode/settings.json b/js/.vscode/settings.json new file mode 100644 index 0000000..dab99f9 --- /dev/null +++ b/js/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "eslint.workingDirectories": ["./js"] +} \ No newline at end of file diff --git a/js/Makefile.jinja b/js/Makefile.jinja index 761a458..b4faca1 100644 --- a/js/Makefile.jinja +++ b/js/Makefile.jinja @@ -34,12 +34,16 @@ lint-py: ## run python linter with ruff lint-js: ## run js linter cd js; pnpm lint -lint: lint-js lint-py ## run project linters +lint-docs: ## lint docs with mdformat and codespell + python -m mdformat --check README.md {% if add_wiki %}docs/wiki/{% endif %} + python -m codespell_lib README.md {% if add_wiki %}docs/wiki/{% endif %} + +lint: lint-js lint-py lint-docs ## run project linters # alias lints: lint -.PHONY: fix-py fix-js fix format +.PHONY: fix-py fix-js fix-docs fix format fix-py: ## fix python formatting with ruff python -m ruff check --fix {{module}} python -m ruff format {{module}} @@ -47,7 +51,11 @@ fix-py: ## fix python formatting with ruff fix-js: ## fix js formatting cd js; pnpm fix -fix: fix-js fix-py ## run project autoformatters +fix-docs: ## autoformat docs with mdformat and codespell + python -m mdformat README.md {% if add_wiki %}docs/wiki/{% endif %} + python -m codespell_lib --write README.md {% if add_wiki %}docs/wiki/{% endif %} + +fix: fix-js fix-py fix-docs ## run project autoformatters # alias format: fix diff --git a/js/README.md.jinja b/js/README.md.jinja index ee722e1..d8ce83b 100644 --- a/js/README.md.jinja +++ b/js/README.md.jinja @@ -9,6 +9,5 @@ ## Overview - > [!NOTE] > This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base). diff --git a/js/pyproject.toml.jinja b/js/pyproject.toml.jinja index 0e49eb0..7d89f5f 100644 --- a/js/pyproject.toml.jinja +++ b/js/pyproject.toml.jinja @@ -35,8 +35,11 @@ develop = [ "build", "bump-my-version", "check-manifest", + "codespell>=2.4,<2.5", "hatch-jupyter-builder", "hatchling", + "mdformat>=0.7.22,<0.8", + "mdformat-tables>=1", "pytest", "pytest-cov", "ruff", @@ -54,6 +57,7 @@ Homepage = "https://github.com/{{github}}/{{project_name_formatted}}" current_version = "0.1.0" commit = true tag = true +commit_args = "-s" [[tool.bumpversion.files]] filename = "{{module}}/__init__.py" @@ -75,6 +79,7 @@ ignore = [ ".copier-answers.yaml", "js/pnpm-lock.yaml", "Makefile", + ".vscode/*", "{{module}}/extension/**/*", "docs/**/*", "js/dist/**/*", diff --git a/js/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja b/js/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja new file mode 100644 index 0000000..4a5fb4b --- /dev/null +++ b/js/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja @@ -0,0 +1 @@ +_This wiki is autogenerated. To made updates, open a PR against the original source file in [`docs/wiki`](https://github.com/{{github}}/{{project_name_formatted}}/tree/main/docs/wiki)._ diff --git a/js/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja b/js/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja new file mode 100644 index 0000000..988b1ac --- /dev/null +++ b/js/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja @@ -0,0 +1,16 @@ + + +**[Home](Home)** + +**Get Started** + +- [Installation](Installation) +- [Contributing](Contribute) +- [Development Setup](Local-Development-Setup) +- [Build from Source](Build-from-Source) diff --git a/js/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja b/js/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja new file mode 100644 index 0000000..7431b53 --- /dev/null +++ b/js/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja @@ -0,0 +1,131 @@ +`{{project_name_formatted}}` is written in Python and JavaScript. While prebuilt wheels are provided for end users, it is also straightforward to build `{{project_name_formatted}}` from either the Python [source distribution](https://packaging.python.org/en/latest/specifications/source-distribution-format/) or the GitHub repository. + +- [Make commands](#make-commands) +- [Prerequisites](#prerequisites) +- [Clone](#clone) +- [Install Python dependencies](#install-python-dependencies) +- [Build](#build) +- [Lint and Autoformat](#lint-and-autoformat) +- [Testing](#testing) + +## Make commands + +As a convenience, `{{project_name_formatted}}` uses a `Makefile` for commonly used commands. You can print the main available commands by running `make` with no arguments + +```bash +> make + +build build the library +clean clean the repository +fix run autofixers +install install library +lint run lints +test run the tests +``` + +## Prerequisites + +`{{project_name_formatted}}` has a few system-level dependencies which you can install from your machine package manager. Other package managers like `conda`, `nix`, etc, should also work fine. + +## Clone + +Clone the repo with: + +```bash +git clone https://github.com/{{github}}/{{project_name_formatted}}.git +cd {{project_name_formatted}} +``` + +## Install NodeJS + +Follow the instructions for [installing NodeJS](https://nodejs.org/en/download/package-manager/all) for your system. Once installed, you can [install `pnpm`](https://pnpm.io/installation) with: + +```bash +npm install --global pnpm +``` + +## Install Python dependencies + +Python build and develop dependencies are specified in the `pyproject.toml`, but you can manually install them: + +```bash +make requirements +``` + +Note that these dependencies would otherwise be installed normally as part of [PEP517](https://peps.python.org/pep-0517/) / [PEP518](https://peps.python.org/pep-0518/). + +## Build + +Build the python project in the usual manner: + +```bash +make build +``` + +## Lint and Autoformat + +`{{project_name_formatted}}` has linting and auto formatting. + +| Language | Linter | Autoformatter | Description | +| :--------- | :---------- | :------------ | :---------- | +| Python | `ruff` | `ruff` | Style | +| Python | `ruff` | `ruff` | Imports | +| JavaScript | `prettier` | `prettier` | Style | +| Markdown | `mdformat` | `mdformat` | Style | +| Markdown | `codespell` | | Spelling | + +**Python Linting** + +```bash +make lint-py +``` + +**Python Autoformatting** + +```bash +make fix-py +``` + +**JavaScript Linting** + +```bash +make lint-js +``` + +**JavaScript Autoformatting** + +```bash +make fix-js +``` + +**Documentation Linting** + +```bash +make lint-docs +``` + +**Documentation Autoformatting** + +```bash +make fix-docs +``` + +## Testing + +`{{project_name_formatted}}` has both Python and JavaScript tests. The bulk of the functionality is tested in Python, which can be run via `pytest`. First, install the Python development dependencies with + +```bash +make develop +``` + +**Python** + +```bash +make test-py +``` + +**JavaScript** + +```bash +make test-js +``` diff --git a/js/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja b/js/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja new file mode 100644 index 0000000..7deea95 --- /dev/null +++ b/js/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja @@ -0,0 +1,15 @@ +Contributions are welcome on this project. We distribute under the terms of the [Apache 2.0 license](https://github.com/{{github}}/{{project_name_formatted}}/blob/main/LICENSE). + +> [!NOTE] +> +> `{{project_name_formatted}}` requires [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions. +> This is enforced by a [Probot GitHub App](https://probot.github.io/apps/dco/), which checks that commits are "signed". +> Read [instructions to configure commit signing](Local-Development-Setup#configure-commit-signing). + +For **bug reports** or **small feature requests**, please open an issue on our [issues page](https://github.com/{{github}}/{{project_name_formatted}}/issues). + +For **questions** or to discuss **larger changes or features**, please use our [discussions page](https://github.com/{{github}}/{{project_name_formatted}}/discussions). + +For **contributions**, please see our [developer documentation](Local-Development-Setup). We have `help wanted` and `good first issue` tags on our issues page, so these are a great place to start. + +For **documentation updates**, make PRs that update the pages in `/docs/wiki`. The documentation is pushed to the GitHub wiki automatically through a GitHub workflow. Note that direct updates to this wiki will be overwritten. diff --git a/js/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja b/js/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja new file mode 100644 index 0000000..897872a --- /dev/null +++ b/js/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja @@ -0,0 +1,55 @@ +## Table of Contents + +- [Table of Contents](#table-of-contents) +- [Step 1: Build from Source](#step-1-build-from-source) +- [Step 2: Configuring Git and GitHub for Development](#step-2-configuring-git-and-github-for-development) + - [Create your fork](#create-your-fork) + - [Configure remotes](#configure-remotes) + - [Authenticating with GitHub](#authenticating-with-github) +- [Guidelines](#guidelines) + +## Step 1: Build from Source + +To work on `{{project_name_formatted}}`, you are going to need to build it from source. See +[Build from Source](Build-from-Source) for +detailed build instructions. + +Once you've built `{{project_name_formatted}}` from a `git` clone, you will also need to +configure `git` and your GitHub account for `{{project_name_formatted}}` development. + +## Step 2: Configuring Git and GitHub for Development + +### Create your fork + +The first step is to create a personal fork of `{{project_name_formatted}}`. To do so, click +the "fork" button at https://github.com/{{github}}/{{project_name_formatted}}, or just navigate +[here](https://github.com/{{github}}/{{project_name_formatted}}/fork) in your browser. Set the +owner of the repository to your personal GitHub account if it is not +already set that way and click "Create fork". + +### Configure remotes + +Next, you should set some names for the `git` remotes corresponding to +main {{github}} repository and your fork. See the [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork) for more information. + +### Authenticating with GitHub + +If you have not already configured `ssh` access to GitHub, you can find +instructions to do so +[here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh), +including instructions to create an SSH key if you have not done +so. Authenticating with SSH is usually the easiest route. If you are working in +an environment that does not allow SSH connections to GitHub, you can look into +[configuring a hardware +passkey](https://docs.github.com/en/authentication/authenticating-with-a-passkey/about-passkeys) +or adding a [personal access +token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) +to avoid the need to type in your password every time you push to your fork. + +## Guidelines + +After developing a change locally, ensure that both [lints](Build-from-Source#lint-and-autoformat) and [tests](Build-from-Source#testing) pass. Commits should be squashed into logical units, and all commits must be signed (e.g. with the `-s` git flag). We require [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions. + +If your work is still in-progress, open a [draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests). Otherwise, open a normal pull request. It might take a few days for a maintainer to review and provide feedback, so please be patient. If a maintainer asks for changes, please make said changes and squash your commits if necessary. If everything looks good to go, a maintainer will approve and merge your changes for inclusion in the next release. + +Please note that non substantive changes, large changes without prior discussion, etc, are not accepted and pull requests may be closed. diff --git a/jupyter/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja b/jupyter/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja new file mode 100644 index 0000000..1588acd --- /dev/null +++ b/jupyter/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja @@ -0,0 +1,27 @@ +name: Publish Docs + +on: + push: + branches: + - main + paths: + - "docs/**" + - "README.md" + workflow_dispatch: + +concurrency: + group: docs + cancel-in-progress: true + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: cp README.md docs/wiki/Home.md + - uses: Andrew-Chen-Wang/github-wiki-action@v4 + with: + path: docs/wiki diff --git a/jupyter/.vscode/settings.json b/jupyter/.vscode/settings.json new file mode 100644 index 0000000..dab99f9 --- /dev/null +++ b/jupyter/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "eslint.workingDirectories": ["./js"] +} \ No newline at end of file diff --git a/jupyter/Makefile.jinja b/jupyter/Makefile.jinja index d15cb52..f59aead 100644 --- a/jupyter/Makefile.jinja +++ b/jupyter/Makefile.jinja @@ -26,7 +26,7 @@ install: ## install python library ######### # LINTS # ######### -.PHONY: lint-py lint-js lint lints +.PHONY: lint-py lint-js lint-docs lint lints lint-py: ## run python linter with ruff python -m ruff check {{module}} python -m ruff format --check {{module}} @@ -34,12 +34,16 @@ lint-py: ## run python linter with ruff lint-js: ## run js linter cd js; pnpm lint -lint: lint-js lint-py ## run project linters +lint-docs: ## lint docs with mdformat and codespell + python -m mdformat --check README.md {% if add_wiki %}docs/wiki/{% endif %} + python -m codespell_lib README.md {% if add_wiki %}docs/wiki/{% endif %} + +lint: lint-js lint-py lint-docs ## run project linters # alias lints: lint -.PHONY: fix-py fix-js fix format +.PHONY: fix-py fix-js fix-docs fix format fix-py: ## fix python formatting with ruff python -m ruff check --fix {{module}} python -m ruff format {{module}} @@ -47,7 +51,11 @@ fix-py: ## fix python formatting with ruff fix-js: ## fix js formatting cd js; pnpm fix -fix: fix-js fix-py ## run project autoformatters +fix-docs: ## autoformat docs with mdformat and codespell + python -m mdformat README.md {% if add_wiki %}docs/wiki/{% endif %} + python -m codespell_lib --write README.md {% if add_wiki %}docs/wiki/{% endif %} + +fix: fix-js fix-py fix-docs ## run project autoformatters # alias format: fix diff --git a/jupyter/README.md.jinja b/jupyter/README.md.jinja index f7ef0b6..1fe56c1 100644 --- a/jupyter/README.md.jinja +++ b/jupyter/README.md.jinja @@ -10,6 +10,5 @@ ## Overview - > [!NOTE] > This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base). diff --git a/jupyter/pyproject.toml.jinja b/jupyter/pyproject.toml.jinja index d1f9eb2..5ec584f 100644 --- a/jupyter/pyproject.toml.jinja +++ b/jupyter/pyproject.toml.jinja @@ -39,7 +39,10 @@ develop = [ "bump-my-version", "check-manifest", "hatch-jupyter-builder", + "codespell>=2.4,<2.5", "hatchling", + "mdformat>=0.7.22,<0.8", + "mdformat-tables>=1", "jupyterlab>=4,<5", "pytest", "pytest-cov", @@ -58,6 +61,7 @@ Homepage = "https://github.com/{{github}}/{{project_name_formatted}}" current_version = "0.1.0" commit = true tag = true +commit_args = "-s" [[tool.bumpversion.files]] filename = "{{module}}/__init__.py" @@ -79,6 +83,7 @@ ignore = [ ".copier-answers.yaml", "js/pnpm-lock.yaml", "Makefile", + ".vscode/*", "{{module}}/labextension/**", "{{module}}/nbextension/**", "docs/**/*", diff --git a/jupyter/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja b/jupyter/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja new file mode 100644 index 0000000..4a5fb4b --- /dev/null +++ b/jupyter/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja @@ -0,0 +1 @@ +_This wiki is autogenerated. To made updates, open a PR against the original source file in [`docs/wiki`](https://github.com/{{github}}/{{project_name_formatted}}/tree/main/docs/wiki)._ diff --git a/jupyter/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja b/jupyter/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja new file mode 100644 index 0000000..988b1ac --- /dev/null +++ b/jupyter/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja @@ -0,0 +1,16 @@ + + +**[Home](Home)** + +**Get Started** + +- [Installation](Installation) +- [Contributing](Contribute) +- [Development Setup](Local-Development-Setup) +- [Build from Source](Build-from-Source) diff --git a/jupyter/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja b/jupyter/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja new file mode 100644 index 0000000..7431b53 --- /dev/null +++ b/jupyter/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja @@ -0,0 +1,131 @@ +`{{project_name_formatted}}` is written in Python and JavaScript. While prebuilt wheels are provided for end users, it is also straightforward to build `{{project_name_formatted}}` from either the Python [source distribution](https://packaging.python.org/en/latest/specifications/source-distribution-format/) or the GitHub repository. + +- [Make commands](#make-commands) +- [Prerequisites](#prerequisites) +- [Clone](#clone) +- [Install Python dependencies](#install-python-dependencies) +- [Build](#build) +- [Lint and Autoformat](#lint-and-autoformat) +- [Testing](#testing) + +## Make commands + +As a convenience, `{{project_name_formatted}}` uses a `Makefile` for commonly used commands. You can print the main available commands by running `make` with no arguments + +```bash +> make + +build build the library +clean clean the repository +fix run autofixers +install install library +lint run lints +test run the tests +``` + +## Prerequisites + +`{{project_name_formatted}}` has a few system-level dependencies which you can install from your machine package manager. Other package managers like `conda`, `nix`, etc, should also work fine. + +## Clone + +Clone the repo with: + +```bash +git clone https://github.com/{{github}}/{{project_name_formatted}}.git +cd {{project_name_formatted}} +``` + +## Install NodeJS + +Follow the instructions for [installing NodeJS](https://nodejs.org/en/download/package-manager/all) for your system. Once installed, you can [install `pnpm`](https://pnpm.io/installation) with: + +```bash +npm install --global pnpm +``` + +## Install Python dependencies + +Python build and develop dependencies are specified in the `pyproject.toml`, but you can manually install them: + +```bash +make requirements +``` + +Note that these dependencies would otherwise be installed normally as part of [PEP517](https://peps.python.org/pep-0517/) / [PEP518](https://peps.python.org/pep-0518/). + +## Build + +Build the python project in the usual manner: + +```bash +make build +``` + +## Lint and Autoformat + +`{{project_name_formatted}}` has linting and auto formatting. + +| Language | Linter | Autoformatter | Description | +| :--------- | :---------- | :------------ | :---------- | +| Python | `ruff` | `ruff` | Style | +| Python | `ruff` | `ruff` | Imports | +| JavaScript | `prettier` | `prettier` | Style | +| Markdown | `mdformat` | `mdformat` | Style | +| Markdown | `codespell` | | Spelling | + +**Python Linting** + +```bash +make lint-py +``` + +**Python Autoformatting** + +```bash +make fix-py +``` + +**JavaScript Linting** + +```bash +make lint-js +``` + +**JavaScript Autoformatting** + +```bash +make fix-js +``` + +**Documentation Linting** + +```bash +make lint-docs +``` + +**Documentation Autoformatting** + +```bash +make fix-docs +``` + +## Testing + +`{{project_name_formatted}}` has both Python and JavaScript tests. The bulk of the functionality is tested in Python, which can be run via `pytest`. First, install the Python development dependencies with + +```bash +make develop +``` + +**Python** + +```bash +make test-py +``` + +**JavaScript** + +```bash +make test-js +``` diff --git a/jupyter/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja b/jupyter/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja new file mode 100644 index 0000000..7deea95 --- /dev/null +++ b/jupyter/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja @@ -0,0 +1,15 @@ +Contributions are welcome on this project. We distribute under the terms of the [Apache 2.0 license](https://github.com/{{github}}/{{project_name_formatted}}/blob/main/LICENSE). + +> [!NOTE] +> +> `{{project_name_formatted}}` requires [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions. +> This is enforced by a [Probot GitHub App](https://probot.github.io/apps/dco/), which checks that commits are "signed". +> Read [instructions to configure commit signing](Local-Development-Setup#configure-commit-signing). + +For **bug reports** or **small feature requests**, please open an issue on our [issues page](https://github.com/{{github}}/{{project_name_formatted}}/issues). + +For **questions** or to discuss **larger changes or features**, please use our [discussions page](https://github.com/{{github}}/{{project_name_formatted}}/discussions). + +For **contributions**, please see our [developer documentation](Local-Development-Setup). We have `help wanted` and `good first issue` tags on our issues page, so these are a great place to start. + +For **documentation updates**, make PRs that update the pages in `/docs/wiki`. The documentation is pushed to the GitHub wiki automatically through a GitHub workflow. Note that direct updates to this wiki will be overwritten. diff --git a/jupyter/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja b/jupyter/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja new file mode 100644 index 0000000..897872a --- /dev/null +++ b/jupyter/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja @@ -0,0 +1,55 @@ +## Table of Contents + +- [Table of Contents](#table-of-contents) +- [Step 1: Build from Source](#step-1-build-from-source) +- [Step 2: Configuring Git and GitHub for Development](#step-2-configuring-git-and-github-for-development) + - [Create your fork](#create-your-fork) + - [Configure remotes](#configure-remotes) + - [Authenticating with GitHub](#authenticating-with-github) +- [Guidelines](#guidelines) + +## Step 1: Build from Source + +To work on `{{project_name_formatted}}`, you are going to need to build it from source. See +[Build from Source](Build-from-Source) for +detailed build instructions. + +Once you've built `{{project_name_formatted}}` from a `git` clone, you will also need to +configure `git` and your GitHub account for `{{project_name_formatted}}` development. + +## Step 2: Configuring Git and GitHub for Development + +### Create your fork + +The first step is to create a personal fork of `{{project_name_formatted}}`. To do so, click +the "fork" button at https://github.com/{{github}}/{{project_name_formatted}}, or just navigate +[here](https://github.com/{{github}}/{{project_name_formatted}}/fork) in your browser. Set the +owner of the repository to your personal GitHub account if it is not +already set that way and click "Create fork". + +### Configure remotes + +Next, you should set some names for the `git` remotes corresponding to +main {{github}} repository and your fork. See the [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork) for more information. + +### Authenticating with GitHub + +If you have not already configured `ssh` access to GitHub, you can find +instructions to do so +[here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh), +including instructions to create an SSH key if you have not done +so. Authenticating with SSH is usually the easiest route. If you are working in +an environment that does not allow SSH connections to GitHub, you can look into +[configuring a hardware +passkey](https://docs.github.com/en/authentication/authenticating-with-a-passkey/about-passkeys) +or adding a [personal access +token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) +to avoid the need to type in your password every time you push to your fork. + +## Guidelines + +After developing a change locally, ensure that both [lints](Build-from-Source#lint-and-autoformat) and [tests](Build-from-Source#testing) pass. Commits should be squashed into logical units, and all commits must be signed (e.g. with the `-s` git flag). We require [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions. + +If your work is still in-progress, open a [draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests). Otherwise, open a normal pull request. It might take a few days for a maintainer to review and provide feedback, so please be patient. If a maintainer asks for changes, please make said changes and squash your commits if necessary. If everything looks good to go, a maintainer will approve and merge your changes for inclusion in the next release. + +Please note that non substantive changes, large changes without prior discussion, etc, are not accepted and pull requests may be closed. diff --git a/python/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja b/python/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja new file mode 100644 index 0000000..1588acd --- /dev/null +++ b/python/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja @@ -0,0 +1,27 @@ +name: Publish Docs + +on: + push: + branches: + - main + paths: + - "docs/**" + - "README.md" + workflow_dispatch: + +concurrency: + group: docs + cancel-in-progress: true + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: cp README.md docs/wiki/Home.md + - uses: Andrew-Chen-Wang/github-wiki-action@v4 + with: + path: docs/wiki diff --git a/python/Makefile.jinja b/python/Makefile.jinja index 73b9815..9a4336f 100644 --- a/python/Makefile.jinja +++ b/python/Makefile.jinja @@ -15,20 +15,27 @@ install: ## install library ######### # LINTS # ######### -.PHONY: lint lints fix format +.PHONY: lint-py lint-docs fix-py fix-docs lint lints fix format -lint: ## run python linter with ruff +lint-py: ## lint python with ruff python -m ruff check {{module}} python -m ruff format --check {{module}} -# Alias -lints: lint +lint-docs: ## lint docs with mdformat and codespell + python -m mdformat --check README.md {% if add_wiki %}docs/wiki/{% endif %} + python -m codespell_lib README.md {% if add_wiki %}docs/wiki/{% endif %} -fix: ## fix python formatting with ruff +fix-py: ## autoformat python code with ruff python -m ruff check --fix {{module}} python -m ruff format {{module}} -# alias +fix-docs: ## autoformat docs with mdformat and codespell + python -m mdformat README.md {% if add_wiki %}docs/wiki/{% endif %} + python -m codespell_lib --write README.md {% if add_wiki %}docs/wiki/{% endif %} + +lint: lint-py lint-docs ## run all linters +lints: lint +fix: fix-py fix-docs ## run all autoformatters format: fix ################ diff --git a/python/README.md.jinja b/python/README.md.jinja index ee722e1..d8ce83b 100644 --- a/python/README.md.jinja +++ b/python/README.md.jinja @@ -9,6 +9,5 @@ ## Overview - > [!NOTE] > This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base). diff --git a/python/pyproject.toml.jinja b/python/pyproject.toml.jinja index 3fa13ae..c23db2b 100644 --- a/python/pyproject.toml.jinja +++ b/python/pyproject.toml.jinja @@ -32,7 +32,10 @@ develop = [ "build", "bump-my-version", "check-manifest", + "codespell>=2.4,<2.5", "hatchling", + "mdformat>=0.7.22,<0.8", + "mdformat-tables>=1", "pytest", "pytest-cov", "ruff", @@ -51,6 +54,7 @@ Homepage = "https://github.com/{{github}}/{{project_name_formatted}}" current_version = "0.1.0" commit = true tag = true +commit_args = "-s" [[tool.bumpversion.files]] filename = "{{module}}/__init__.py" diff --git a/python/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja b/python/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja new file mode 100644 index 0000000..4a5fb4b --- /dev/null +++ b/python/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja @@ -0,0 +1 @@ +_This wiki is autogenerated. To made updates, open a PR against the original source file in [`docs/wiki`](https://github.com/{{github}}/{{project_name_formatted}}/tree/main/docs/wiki)._ diff --git a/python/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja b/python/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja new file mode 100644 index 0000000..988b1ac --- /dev/null +++ b/python/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja @@ -0,0 +1,16 @@ + + +**[Home](Home)** + +**Get Started** + +- [Installation](Installation) +- [Contributing](Contribute) +- [Development Setup](Local-Development-Setup) +- [Build from Source](Build-from-Source) diff --git a/python/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja b/python/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja new file mode 100644 index 0000000..ff2651e --- /dev/null +++ b/python/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja @@ -0,0 +1,103 @@ +`{{project_name_formatted}}` is written in Python. While prebuilt wheels are provided for end users, it is also straightforward to build `{{project_name_formatted}}` from either the Python [source distribution](https://packaging.python.org/en/latest/specifications/source-distribution-format/) or the GitHub repository. + +- [Make commands](#make-commands) +- [Prerequisites](#prerequisites) +- [Clone](#clone) +- [Install Python dependencies](#install-python-dependencies) +- [Build](#build) +- [Lint and Autoformat](#lint-and-autoformat) +- [Testing](#testing) + +## Make commands + +As a convenience, `{{project_name_formatted}}` uses a `Makefile` for commonly used commands. You can print the main available commands by running `make` with no arguments + +```bash +> make + +build build the library +clean clean the repository +fix run autofixers +install install library +lint run lints +test run the tests +``` + +## Prerequisites + +`{{project_name_formatted}}` has a few system-level dependencies which you can install from your machine package manager. Other package managers like `conda`, `nix`, etc, should also work fine. + +## Clone + +Clone the repo with: + +```bash +git clone https://github.com/{{github}}/{{project_name_formatted}}.git +cd {{project_name_formatted}} +``` + +## Install Python dependencies + +Python build and develop dependencies are specified in the `pyproject.toml`, but you can manually install them: + +```bash +make requirements +``` + +Note that these dependencies would otherwise be installed normally as part of [PEP517](https://peps.python.org/pep-0517/) / [PEP518](https://peps.python.org/pep-0518/). + +## Build + +Build the python project in the usual manner: + +```bash +make build +``` + +## Lint and Autoformat + +`{{project_name_formatted}}` has linting and auto formatting. + +| Language | Linter | Autoformatter | Description | +| :------- | :---------- | :------------ | :---------- | +| Python | `ruff` | `ruff` | Style | +| Markdown | `mdformat` | `mdformat` | Style | +| Markdown | `codespell` | | Spelling | + +**Python Linting** + +```bash +make lint-py +``` + +**Python Autoformatting** + +```bash +make fix-py +``` + +**Documentation Linting** + +```bash +make lint-docs +``` + +**Documentation Autoformatting** + +```bash +make fix-docs +``` + +## Testing + +`{{project_name_formatted}}` has extensive Python tests. The tests can be run via `pytest`. First, install the Python development dependencies with + +```bash +make develop +``` + +**Python** + +```bash +make test +``` diff --git a/python/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja b/python/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja new file mode 100644 index 0000000..7deea95 --- /dev/null +++ b/python/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja @@ -0,0 +1,15 @@ +Contributions are welcome on this project. We distribute under the terms of the [Apache 2.0 license](https://github.com/{{github}}/{{project_name_formatted}}/blob/main/LICENSE). + +> [!NOTE] +> +> `{{project_name_formatted}}` requires [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions. +> This is enforced by a [Probot GitHub App](https://probot.github.io/apps/dco/), which checks that commits are "signed". +> Read [instructions to configure commit signing](Local-Development-Setup#configure-commit-signing). + +For **bug reports** or **small feature requests**, please open an issue on our [issues page](https://github.com/{{github}}/{{project_name_formatted}}/issues). + +For **questions** or to discuss **larger changes or features**, please use our [discussions page](https://github.com/{{github}}/{{project_name_formatted}}/discussions). + +For **contributions**, please see our [developer documentation](Local-Development-Setup). We have `help wanted` and `good first issue` tags on our issues page, so these are a great place to start. + +For **documentation updates**, make PRs that update the pages in `/docs/wiki`. The documentation is pushed to the GitHub wiki automatically through a GitHub workflow. Note that direct updates to this wiki will be overwritten. diff --git a/python/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja b/python/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja new file mode 100644 index 0000000..897872a --- /dev/null +++ b/python/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja @@ -0,0 +1,55 @@ +## Table of Contents + +- [Table of Contents](#table-of-contents) +- [Step 1: Build from Source](#step-1-build-from-source) +- [Step 2: Configuring Git and GitHub for Development](#step-2-configuring-git-and-github-for-development) + - [Create your fork](#create-your-fork) + - [Configure remotes](#configure-remotes) + - [Authenticating with GitHub](#authenticating-with-github) +- [Guidelines](#guidelines) + +## Step 1: Build from Source + +To work on `{{project_name_formatted}}`, you are going to need to build it from source. See +[Build from Source](Build-from-Source) for +detailed build instructions. + +Once you've built `{{project_name_formatted}}` from a `git` clone, you will also need to +configure `git` and your GitHub account for `{{project_name_formatted}}` development. + +## Step 2: Configuring Git and GitHub for Development + +### Create your fork + +The first step is to create a personal fork of `{{project_name_formatted}}`. To do so, click +the "fork" button at https://github.com/{{github}}/{{project_name_formatted}}, or just navigate +[here](https://github.com/{{github}}/{{project_name_formatted}}/fork) in your browser. Set the +owner of the repository to your personal GitHub account if it is not +already set that way and click "Create fork". + +### Configure remotes + +Next, you should set some names for the `git` remotes corresponding to +main {{github}} repository and your fork. See the [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork) for more information. + +### Authenticating with GitHub + +If you have not already configured `ssh` access to GitHub, you can find +instructions to do so +[here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh), +including instructions to create an SSH key if you have not done +so. Authenticating with SSH is usually the easiest route. If you are working in +an environment that does not allow SSH connections to GitHub, you can look into +[configuring a hardware +passkey](https://docs.github.com/en/authentication/authenticating-with-a-passkey/about-passkeys) +or adding a [personal access +token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) +to avoid the need to type in your password every time you push to your fork. + +## Guidelines + +After developing a change locally, ensure that both [lints](Build-from-Source#lint-and-autoformat) and [tests](Build-from-Source#testing) pass. Commits should be squashed into logical units, and all commits must be signed (e.g. with the `-s` git flag). We require [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions. + +If your work is still in-progress, open a [draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests). Otherwise, open a normal pull request. It might take a few days for a maintainer to review and provide feedback, so please be patient. If a maintainer asks for changes, please make said changes and squash your commits if necessary. If everything looks good to go, a maintainer will approve and merge your changes for inclusion in the next release. + +Please note that non substantive changes, large changes without prior discussion, etc, are not accepted and pull requests may be closed. diff --git a/rust/.github/workflows/build.yaml.jinja b/rust/.github/workflows/build.yaml.jinja index b168757..df5628b 100644 --- a/rust/.github/workflows/build.yaml.jinja +++ b/rust/.github/workflows/build.yaml.jinja @@ -83,7 +83,7 @@ jobs: - name: Make dist run: | - make dist-rust + make dist-rs make dist-py-sdist make dist-py-wheel make dist-check diff --git a/rust/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja b/rust/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja new file mode 100644 index 0000000..1588acd --- /dev/null +++ b/rust/.github/workflows/{% if add_wiki %}wiki.yaml{% endif %}.jinja @@ -0,0 +1,27 @@ +name: Publish Docs + +on: + push: + branches: + - main + paths: + - "docs/**" + - "README.md" + workflow_dispatch: + +concurrency: + group: docs + cancel-in-progress: true + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: cp README.md docs/wiki/Home.md + - uses: Andrew-Chen-Wang/github-wiki-action@v4 + with: + path: docs/wiki diff --git a/rust/Makefile.jinja b/rust/Makefile.jinja index 8d87f23..e93defd 100644 --- a/rust/Makefile.jinja +++ b/rust/Makefile.jinja @@ -1,26 +1,26 @@ ######### # BUILD # ######### -.PHONY: develop-py develop-rust develop +.PHONY: develop-py develop-rs develop develop-py: uv pip install -e .[develop] -develop-rust: +develop-rs: make -C rust develop -develop: develop-rust develop-py ## setup project for development +develop: develop-rs develop-py ## setup project for development -.PHONY: build-py build-rust build dev +.PHONY: build-py build-rs build dev build-py: maturin build -build-rust: +build-rs: make -C rust build dev: build ## lightweight in-place build for iterative dev $(_CP_COMMAND) -build: build-rust build-py ## build the project +build: build-rs build-py ## build the project .PHONY: install install: ## install python library @@ -36,28 +36,36 @@ endif ######### # LINTS # ######### -.PHONY: lint-py lint-rust lint lints +.PHONY: lint-py lint-rs lint-docs lint lints lint-py: ## run python linter with ruff python -m ruff check {{module}} python -m ruff format --check {{module}} -lint-rust: ## run rust linter +lint-rs: ## run rust linter make -C rust lint -lint: lint-rust lint-py ## run project linters +lint-docs: ## lint docs with mdformat and codespell + python -m mdformat --check README.md {% if add_wiki %}docs/wiki/{% endif %} + python -m codespell_lib README.md {% if add_wiki %}docs/wiki/{% endif %} + +lint: lint-rs lint-py lint-docs ## run project linters # alias lints: lint -.PHONY: fix-py fix-rust fix format +.PHONY: fix-py fix-rs fix-docs fix format fix-py: ## fix python formatting with ruff python -m ruff check --fix {{module}} python -m ruff format {{module}} -fix-rust: ## fix rust formatting +fix-rs: ## fix rust formatting make -C rust fix -fix: fix-rust fix-py ## run project autoformatters +fix-docs: ## autoformat docs with mdformat and codespell + python -m mdformat README.md {% if add_wiki %}docs/wiki/{% endif %} + python -m codespell_lib --write README.md {% if add_wiki %}docs/wiki/{% endif %} + +fix: fix-rs fix-py fix-docs ## run project autoformatters # alias format: fix @@ -88,19 +96,19 @@ tests-py: test-py coverage-py: ## run python tests and collect test coverage python -m pytest -v {{module}}/tests --cov={{module}} --cov-report term-missing --cov-report xml -.PHONY: test-rust tests-rust coverage-rust -test-rust: ## run rust tests +.PHONY: test-rs tests-rs coverage-rs +test-rs: ## run rust tests make -C rust test # alias -tests-rust: test-rust +tests-rs: test-rs -coverage-rust: ## run rust tests and collect test coverage +coverage-rs: ## run rust tests and collect test coverage make -C rust coverage .PHONY: test coverage tests -test: test-py test-rust ## run all tests -coverage: coverage-py coverage-rust ## run all tests and collect test coverage +test: test-py test-rs ## run all tests +coverage: coverage-py coverage-rs ## run all tests and collect test coverage # alias tests: test @@ -125,7 +133,7 @@ major: ## bump a major version ######## # DIST # ######## -.PHONY: dist-py-wheel dist-py-sdist dist-rust dist-check dist publish +.PHONY: dist-py-wheel dist-py-sdist dist-rs dist-check dist publish dist-py-wheel: # build python wheel python -m cibuildwheel --output-dir dist @@ -133,13 +141,13 @@ dist-py-wheel: # build python wheel dist-py-sdist: # build python sdist python -m build --sdist -o dist -dist-rust: # build rust dists +dist-rs: # build rust dists make -C rust dist dist-check: ## run python dist checker with twine python -m twine check dist/* -dist: clean build dist-rust dist-py-wheel dist-py-sdist dist-check ## build all dists +dist: clean build dist-rs dist-py-wheel dist-py-sdist dist-check ## build all dists publish: dist # publish python assets diff --git a/rust/README.md.jinja b/rust/README.md.jinja index ee722e1..d8ce83b 100644 --- a/rust/README.md.jinja +++ b/rust/README.md.jinja @@ -9,6 +9,5 @@ ## Overview - > [!NOTE] > This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base). diff --git a/rust/pyproject.toml.jinja b/rust/pyproject.toml.jinja index bbd6472..c1a6d6a 100644 --- a/rust/pyproject.toml.jinja +++ b/rust/pyproject.toml.jinja @@ -34,6 +34,9 @@ develop = [ "bump-my-version", "check-manifest", "cibuildwheel", + "codespell>=2.4,<2.5", + "mdformat>=0.7.22,<0.8", + "mdformat-tables>=1", "maturin>=1,<2", "pytest", "pytest-cov", @@ -52,6 +55,7 @@ Homepage = "https://github.com/{{github}}/{{project_name_formatted}}" current_version = "0.1.0" commit = true tag = true +commit_args = "-s" [[tool.bumpversion.files]] filename = "{{module}}/__init__.py" diff --git a/rust/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja b/rust/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja new file mode 100644 index 0000000..4a5fb4b --- /dev/null +++ b/rust/{% if add_wiki %}docs{% endif %}/wiki/_Footer.md.jinja @@ -0,0 +1 @@ +_This wiki is autogenerated. To made updates, open a PR against the original source file in [`docs/wiki`](https://github.com/{{github}}/{{project_name_formatted}}/tree/main/docs/wiki)._ diff --git a/rust/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja b/rust/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja new file mode 100644 index 0000000..988b1ac --- /dev/null +++ b/rust/{% if add_wiki %}docs{% endif %}/wiki/_Sidebar.md.jinja @@ -0,0 +1,16 @@ + + +**[Home](Home)** + +**Get Started** + +- [Installation](Installation) +- [Contributing](Contribute) +- [Development Setup](Local-Development-Setup) +- [Build from Source](Build-from-Source) diff --git a/rust/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja b/rust/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja new file mode 100644 index 0000000..78ceceb --- /dev/null +++ b/rust/{% if add_wiki %}docs{% endif %}/wiki/contribute/Build-from-Source.md.jinja @@ -0,0 +1,127 @@ +`{{project_name_formatted}}` is written in Python and Rust. While prebuilt wheels are provided for end users, it is also straightforward to build `{{project_name_formatted}}` from either the Python [source distribution](https://packaging.python.org/en/latest/specifications/source-distribution-format/) or the GitHub repository. + +- [Make commands](#make-commands) +- [Prerequisites](#prerequisites) +- [Clone](#clone) +- [Install Python dependencies](#install-python-dependencies) +- [Build](#build) +- [Lint and Autoformat](#lint-and-autoformat) +- [Testing](#testing) + +## Make commands + +As a convenience, `{{project_name_formatted}}` uses a `Makefile` for commonly used commands. You can print the main available commands by running `make` with no arguments + +```bash +> make + +build build the library +clean clean the repository +fix run autofixers +install install library +lint run lints +test run the tests +``` + +## Prerequisites + +`{{project_name_formatted}}` has a few system-level dependencies which you can install from your machine package manager. Other package managers like `conda`, `nix`, etc, should also work fine. + +## Clone + +Clone the repo with: + +```bash +git clone https://github.com/{{github}}/{{project_name_formatted}}.git +cd {{project_name_formatted}} +``` + +## Install Rust + +Follow the instructions for [installing Rust](https://rustup.rs) for your system. + +## Install Python dependencies + +Python build and develop dependencies are specified in the `pyproject.toml`, but you can manually install them: + +```bash +make requirements +``` + +Note that these dependencies would otherwise be installed normally as part of [PEP517](https://peps.python.org/pep-0517/) / [PEP518](https://peps.python.org/pep-0518/). + +## Build + +Build the python project in the usual manner: + +```bash +make build +``` + +## Lint and Autoformat + +`{{project_name_formatted}}` has linting and auto formatting. + +| Language | Linter | Autoformatter | Description | +| :------- | :---------- | :------------ | :---------- | +| Python | `ruff` | `ruff` | Style | +| Python | `ruff` | `ruff` | Imports | +| Rust | `clippy` | `clippy` | Style | +| Markdown | `mdformat` | `mdformat` | Style | +| Markdown | `codespell` | | Spelling | + +**Python Linting** + +```bash +make lint-py +``` + +**Python Autoformatting** + +```bash +make fix-py +``` + +**Rust Linting** + +```bash +make lint-rs +``` + +**Rust Autoformatting** + +```bash +make fix-rs +``` + +**Documentation Linting** + +```bash +make lint-docs +``` + +**Documentation Autoformatting** + +```bash +make fix-docs +``` + +## Testing + +`{{project_name_formatted}}` has both Python and JavaScript tests. The bulk of the functionality is tested in Python, which can be run via `pytest`. First, install the Python development dependencies with + +```bash +make develop +``` + +**Python** + +```bash +make test-py +``` + +**Rust** + +```bash +make test-rs +``` diff --git a/rust/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja b/rust/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja new file mode 100644 index 0000000..7deea95 --- /dev/null +++ b/rust/{% if add_wiki %}docs{% endif %}/wiki/contribute/Contribute.md.jinja @@ -0,0 +1,15 @@ +Contributions are welcome on this project. We distribute under the terms of the [Apache 2.0 license](https://github.com/{{github}}/{{project_name_formatted}}/blob/main/LICENSE). + +> [!NOTE] +> +> `{{project_name_formatted}}` requires [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions. +> This is enforced by a [Probot GitHub App](https://probot.github.io/apps/dco/), which checks that commits are "signed". +> Read [instructions to configure commit signing](Local-Development-Setup#configure-commit-signing). + +For **bug reports** or **small feature requests**, please open an issue on our [issues page](https://github.com/{{github}}/{{project_name_formatted}}/issues). + +For **questions** or to discuss **larger changes or features**, please use our [discussions page](https://github.com/{{github}}/{{project_name_formatted}}/discussions). + +For **contributions**, please see our [developer documentation](Local-Development-Setup). We have `help wanted` and `good first issue` tags on our issues page, so these are a great place to start. + +For **documentation updates**, make PRs that update the pages in `/docs/wiki`. The documentation is pushed to the GitHub wiki automatically through a GitHub workflow. Note that direct updates to this wiki will be overwritten. diff --git a/rust/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja b/rust/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja new file mode 100644 index 0000000..897872a --- /dev/null +++ b/rust/{% if add_wiki %}docs{% endif %}/wiki/contribute/Local-Development-Setup.md.jinja @@ -0,0 +1,55 @@ +## Table of Contents + +- [Table of Contents](#table-of-contents) +- [Step 1: Build from Source](#step-1-build-from-source) +- [Step 2: Configuring Git and GitHub for Development](#step-2-configuring-git-and-github-for-development) + - [Create your fork](#create-your-fork) + - [Configure remotes](#configure-remotes) + - [Authenticating with GitHub](#authenticating-with-github) +- [Guidelines](#guidelines) + +## Step 1: Build from Source + +To work on `{{project_name_formatted}}`, you are going to need to build it from source. See +[Build from Source](Build-from-Source) for +detailed build instructions. + +Once you've built `{{project_name_formatted}}` from a `git` clone, you will also need to +configure `git` and your GitHub account for `{{project_name_formatted}}` development. + +## Step 2: Configuring Git and GitHub for Development + +### Create your fork + +The first step is to create a personal fork of `{{project_name_formatted}}`. To do so, click +the "fork" button at https://github.com/{{github}}/{{project_name_formatted}}, or just navigate +[here](https://github.com/{{github}}/{{project_name_formatted}}/fork) in your browser. Set the +owner of the repository to your personal GitHub account if it is not +already set that way and click "Create fork". + +### Configure remotes + +Next, you should set some names for the `git` remotes corresponding to +main {{github}} repository and your fork. See the [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork) for more information. + +### Authenticating with GitHub + +If you have not already configured `ssh` access to GitHub, you can find +instructions to do so +[here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh), +including instructions to create an SSH key if you have not done +so. Authenticating with SSH is usually the easiest route. If you are working in +an environment that does not allow SSH connections to GitHub, you can look into +[configuring a hardware +passkey](https://docs.github.com/en/authentication/authenticating-with-a-passkey/about-passkeys) +or adding a [personal access +token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) +to avoid the need to type in your password every time you push to your fork. + +## Guidelines + +After developing a change locally, ensure that both [lints](Build-from-Source#lint-and-autoformat) and [tests](Build-from-Source#testing) pass. Commits should be squashed into logical units, and all commits must be signed (e.g. with the `-s` git flag). We require [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions. + +If your work is still in-progress, open a [draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests). Otherwise, open a normal pull request. It might take a few days for a maintainer to review and provide feedback, so please be patient. If a maintainer asks for changes, please make said changes and squash your commits if necessary. If everything looks good to go, a maintainer will approve and merge your changes for inclusion in the next release. + +Please note that non substantive changes, large changes without prior discussion, etc, are not accepted and pull requests may be closed.