Skip to content

Latest commit

 

History

History
152 lines (106 loc) · 4.73 KB

CONTRIBUTING.md

File metadata and controls

152 lines (106 loc) · 4.73 KB

Contributing

This is a personal, very-part-time project, largely driven by my own opinions about how best to configure a Python code base.

Contributions as described below are welcome.

Reporting bugs

If something isn't working as described, or if you find a mistake in the documentation, please feel free to report a bug by opening an issue.

Contributing to the code base

Contributions to the code base are welcome. If you want to add a new feature, please open an issue first. Because pyprefab is an opinion-drive personal project, it's best to make sure our opinions are aligned before doing any work!

If you'd like to tackle an existing issue, please leave a comment on it.

Creating your local development environment

For contributing to this code base, you'll need:

  • A GitHub account
  • Git installed on your machine
  • optional: uv (the Python-based directions below use uv, but if you already have a preferred Python toolset, that should work too)

Important

If you have an active Python virtual environment (for example, conda's base environment), you'll need to deactivate it before following the instructions below.

Configure git

  1. On GitHub, fork this repository.

  2. Clone the forked repository to your machine:

    git clone https://github.com/<username>/pyprefab.git
cd pyprefab

  3. optional: Set the upstream remote to sync your fork with the pyprefab repository:

    git remote add upstream https://github.com/bsweger/pyprefab.git
git fetch upstream

Install project and dependencies

  1. From the root of the repo, create a virtual environment and install the project dependencies. The uv sync command handles installing Python, creating a virtual environment, and installing project dependencies.

    uv sync

    (More information about how uv finds or downloads a Python interpreter)

  2. Run the test suite to check that everything works correctly:

    [!TIP] Prefixing python commands with uv run instructs uv to run the command in the project's virtual environment, even if you haven't explicitly activated it.

    uv run pytest

  3. Install the pre-commit hooks used for linting and other checks (this may take a few minutes but only needs to be done once).

    uv run pre-commit install

  4. Make sure the pre-commit checks are working correctly:

    uv run pre-commit install

Updating your development environment

If time has passed between your initial project setup and when you make changes to the code, make sure your fork and development environment are up-to-date.

  1. Sync your fork to the upstream repository:

    git checkout main
git fetch upstream
git rebase upstream/main
git push origin main

  2. Update your project dependencies:

    uv sync

Adding project dependencies

If your change requires a new dependency, add it as follows:

uv add <dependency>

The uv add command will:

  • Add the dependency to pyproject.toml
  • Install the dependency into the project's virtual environment
  • Update the project's lockfile (uv.lock)

Make sure to commit the updated versions of pyproject.toml and uv.lock.

Submitting code changes

After you've completed the changes described in the issue you're working on, you can submit them by creating a pull request (PR) in the pyprefab repository.

Please ensure the following are true before creating the PR:

  • Your change is covered by tests, if applicable
  • Project documentation is updated, if applicable
  • All tests pass (uv run pytest)
  • All pre-commit checks are successful (these checks will run automatically as you make commits)
  • The [Unreleased] section of CHANGELOG.md contains a description of your change.

The PR itself should:

  • Have a descriptive title
  • Be linked to its corresponding issue in the description.
  • Have a description that includes any other information or context that will help a code reviewer understand your changes.