Contribution Guidelines

Contribution Guidelines#

The project practices test-driven development in Git feature (topic) branches. Please maintain a linear commit history by rebasing changes on the latest HEAD of the main branch before submitting them for review as a GitHub pull request.

Development Environment#

Guidance

This project REQUIRES GNU Make and Python 3.13 or newer.

Additionally, on Linux it needs lsb-release. On macOS it uses the Command Line Tools for Xcode and MacPorts. Several of the available make targets are listed below. Review the makefile for additional details.

make build-deps

Install the remaining system-level build dependencies. Requires root access via sudo.

make setup

Create (or update) a Python virtual environment named .venv in the project root directory and perform an editable installation of this project that includes development and testing tools.

make pre-commit

Configure optional pre-commit hooks, which require the virtual environment to be active in your code editor or Git porcelain.

make lint

Check code syntax and style.

make clean

Reset the development environment, which includes removing the pre-commit hooks.

Code Style#

Guidance

Changes MUST be self-contained and buildable, with updated tests and documentation.

This project follows these code styles:

For actions:

  • Name the folder containing a composite action after the primary tool, e.g., pre-commit/, the runtime and operation, e.g., sphinx-build/, or in special cases, the scenario and target, e.g., setup-bashbrew/.

  • Define the composite action in a file named action.yaml, not action.yml.

  • Specify top-level keys in the order name, description, inputs, runs, and outputs. Group the name and description keys. Put a single blank line between the rest.

  • Name the action and each step with a short sentence in the imperative mood that succinctly explains what the action or that step does. Format names using plain text.

  • For each input, list fields in the order required, default, description, and deprecationMessage. Specify fields only when overriding default values. Sort inputs first by whether they are required and then alphabetically by input name.

  • For each output, list fields in the order description and value. Sort outputs by name.

  • Describe the action, its inputs, and its outputs in detail. Format descriptions using MyST Markdown.

  • If specified, the default value of an input parameter is a string. The GitHub Actions runner will cast other value types to a string. For example, specifying a default value of false results in the input parameter defaulting to "false", a truthy value.

  • The GitHub Actions runner does not check for missing required inputs. Doing so is the responsibility of the action itself.

  • Manually create a corresponding entry in the documentation for each action. List inputs and outputs in the same order as in the action, and keep documentation in sync with the action, input, and output descriptions.

  • Use field lists for inputs and outputs, with a horizontal rule at the end of each definition to separate entries a little without breaking apart the list.

Commit Messages#

Guidance

This project REQUIRES Conventional Commits 1.0.0, with which it implements Semantic Versioning 2.0.0.

In commit messages:

  • Please use English.

  • Limit the first line to at most 100 characters. Wrap the rest of the commit message at column 70.

  • Summarize the changes with a one-sentence commit description in the imperative mood, lowercasing the starting verb and omitting ending punctuation.

  • For the commit type, specify one of build, chore, ci, docs, feat, fix, perf, style, refactor, or test.

Commit Scopes#

Guidance

Per Conventional Commits, a commit scope is an OPTIONAL abbreviation, acronym, codename, or keyword that provides additional context to reviewers by naming the essential component of the change. Changes covering multiple scopes or changes not specific to one scope MUST NOT specify a scope.

An atomic commit can alter multiple files. For example, an interface change could require modifications to class definitions, method calls, property references, and unit tests throughout the project. The commit scope tells reviewers where to focus their analysis. In change logs, commit scopes help sponsors understand the structure of the work going into fixes, features, or breaking changes. Because actions interface with one another (usually indirectly, via workflow artifacts or output/input conventions), commit scopes follow actions’ base names, e.g., pre-commit, not actions/pre-commit, nor ResearchDataCom/actions/pre-commit.

Commit Types#

build

a change to the build system or external dependencies, e.g., the makefile

chore

a miscellaneous tooling or tool configuration change, e.g., the .gitignore file, or a change not covered by the other commit types

ci

a change to continuous integration/continuous delivery (CI/CD) processes, e.g., GitHub Actions

docs

a documentation-only change, including edits to in-line documentation and comments

feat

a new feature

fix

a bug fix

perf

a code change that improves performance

refactor

a code change that neither fixes a bug nor adds a feature

style

a change that only affects formatting, or a change related to the linter configuration

test

a new test or a correction to an existing test