From 076b170fbc70910d1ccd83505baa6db9aec205ea Mon Sep 17 00:00:00 2001 From: Birger Schacht Date: Thu, 5 Sep 2024 15:35:50 +0200 Subject: [PATCH] docs: update the CONTRIBUTING file Closes: #852 --- CONTRIBUTING.md | 52 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 47 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6e9da6a20..a09b2a4ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,9 +45,12 @@ Please try to keep your commit changes focused on the change you want to implement - don't start fixing typos if your commit is actually about adding a feature. -We are using [black](https://github.com/psf/black) for codeformatting and -[djlint](https://github.com/Riverside-Healthcare/djlint) for formatting -templates - the configuration for those is part of our `pyproject.toml`. +We use [ruff](https://docs.astral.sh/ruff/) for linting and +code formatting and [djlint](https://djlint.com/) for +formatting templates - the configuration for those is part of our +[`pyproject.toml`](https://github.com/acdh-oeaw/apis-core-rdf/blob/main/pyproject.toml). +We also check the code using the [deptry](https://deptry.com/) +dependency checker for missing or unused dependencies. Base your commit on the latest changes in `main`. Your work might take some time and other people are also working on APIS, so please rebase your changes @@ -55,9 +58,48 @@ early and often. ### Commit Messages -We are using [conventional +We use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) so please format your -commit messages accordingly. +commit messages accordingly. There is a Github Action that uses the +[Gitlint](https://jorisroovers.com/gitlint/latest/) linter to check your commit +messages for validity. + +Please try to use a scope when writing a commit message. APIS consists of +various individual modules, so the scope tells the users which module your +change refers to. + +Examples: +> `feat(apis_entities): introduce a e53_place autocomplete template` + +[ac358a7e](https://github.com/acdh-oeaw/apis-core-rdf/commit/ac358a7e7d915e756f2de776d5ba95854bb5bd5e) + +or + +> `fix(apis_relations,apis_entities): replace get_object_or_404` + +[6785b802](https://github.com/acdh-oeaw/apis-core-rdf/commit/6785b802f3de88d2cd6d7202bbd88cf9320e1bed) + +Feel free to browse our commit history to get an idea how commit messages +should look like. + +We use the [release-please](https://github.com/googleapis/release-please) +Github Action, which uses the information from the conventional commit messages +to generate changelogs and bump the version. Therefore it is important to use +the correct commit type in the commit message, i.e. `fix` for smaller fixes, +`feat` for new features. Breaking changes have to have an exclamation mark +(`!`) after the type/scope, but please also explain the breaking change in the +commit message body. + +An example how a resulting changelog could look like would be [the changelog of +release 0.26.0](https://github.com/acdh-oeaw/apis-core-rdf/releases/tag/v0.26.0). +Feel free to browse the [releases](https://github.com/acdh-oeaw/apis-core-rdf/releases) +and the [CHANGELOG](CHANGELOG.md) file. + + +## Workflows + +You can see a list of worklows which are run on pull requests +[here](https://github.com/acdh-oeaw/apis-core-rdf/tree/main/.github/workflows). ## Attribution