Developer Guide#

Want to contribute to decent-bench? That’s great! This guide contains useful information about development tools, processes, and rules.

Getting Started#

Prerequisites#

Installation for Development#

git clone https://github.com/team-decent/decent-bench.git
cd decent-bench
tox -e dev                     # create dev env
source .tox/dev/bin/activate   # activate dev env

Tooling#

The dev environment created with tox -e dev has all dependencies and dev-dependencies installed. After activating the dev environment, various tools can be run. Examples include:

mypy decent_bench --strict      # find typing issues
pytest test                     # run tests
ruff check decent_bench --fix   # find and fix style issues
ruff format decent_bench        # format code
make -C docs html               # rebuild html doc files
tox -e sphinx                   # rebuild rst and html doc files
tox                             # run all GitHub status checks

To verify that doc changes look good, use an html previewer such as Live Preview.

CUTE Design Principles#

CUTE is a set of principles that serve as guidelines for code design. They are meant to help keep the codebase simple and the development fast. To mitigate any conflict, the principles are ordered from most to least important:

  1. Correctness: working code is the top priority.

  2. Understandability: others should easily understand your code, avoid bloat, unnecessary indirection, and fancy abstractions.

  3. Testability: code allows for short and clear tests.

  4. Extendability: code allows for future extension, but avoid premature generalization and keep YAGNI and KISS in mind as trying to predict tomorrow’s requirements can cause more problems than it solves.

Pull Requests#

  1. Fork the repository.

  2. Create a feature branch.

  3. Make your changes.

  4. Update documentation as needed.

  5. Run tox to ensure that all checks pass.

  6. Submit a pull request.

  7. Doc changes? Click the readthedocs link found in the status checks to verify that everything looks good.

Commit Messages#

To keep the git history easy to follow, encourage well-scoped PRs, and facilitate changelog writing and versioning, we follow certain rules for commit messages when merging pull requests into main. Each message uses this template:

Template#
<type>(<scope>): <subject> (#<pr-id>)

<description>

closes #<issue-id>
Example#
 perf(costs): Cache m_cvx and m_smooth (#105)

 Cache the properties m_cvx and m_smooth where applicable. This led to a
 75% speed up when running ADMM on a logistic regression problem.

 closes #101
Notes:

  • See table below for types.

  • Scope can be a subpackage, module or build tool, e.g. metrics, costs, or sphinx.

  • Max 72 characters per line.

  • Capitalize but do not punctuate subject.

  • Use imperative mood in subject and description.

  • Description explains what changes and why it changes.

  • If the PR has a related issue but doesn’t close it, skip the “closes”-keyword and simply reference the issue.

Type

Description

feat

New functionality

perf

Performance improvement

ref

Refactor

enh

Small improvement that doesn’t qualify as feat, perf, or ref, e.g. improved variable naming, additional logging, or prettier plots

fix

Bug fix

test

Change to tests

docs

Update to readme, comments, docstrings, rst files, or sphinx config

ci

CI related change, e.g. modifying GitHub checks or tox environments

meta

Update to metadata, e.g. project description, version, or .gitignore

license

License update

Inspired by Sentry.

Releases#

  1. Update the version in pyproject.toml using Semantic Versioning.

  2. Merge the change into main with commit message meta: Bump version to <x>.<y>.<z> (#<pr-id>).

  3. Create a new release on GitHub.

  4. Publish to PyPI using hatch clean && hatch build && hatch publish.