Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
149 lines (116 loc) · 6.17 KB

CONTRIBUTING.md

File metadata and controls

149 lines (116 loc) · 6.17 KB

Contributing to Jockey

Welcome! Thank you for your interest in contributing to Jockey, an open-source community project that aims to simplify operations on large Juju deployments.

Jockey's core querying functionality uses a purely functional programming style keep the scope narrow and maintenance easy. No OOP-style contributions to core Jockey components will be considered.

Contributing at a Glance

  1. First-time contributors
  2. Prepare the development environment
    1. Continuous Integration testing
    2. Local development environment
      1. Check formatting
      2. Fix formatting
      3. Run tests
  3. Submitting changes
  4. Maintainer guidelines

First-time contributors

We reiterate: welcome! If you need help, please check out the issue tracker.

In particular, the following tags are a great start:

You do not need permission to start working on any issue. Just jump in, make sure you add tests, and open a pull request.

To get advice and input on a problem: Add a comment to the issue. If you've encountered a new problem, open a bug. If you have an idea for a new enhancement, open a feature. You're more likely to get help with the more details you provide.

Prepare the development environment

Continuous Integration testing

Jockey uses Continuous Integration (CI) to evaluate all pull requests. When you open a pull request (PR), our automated CI workflows will run against your PR.

Our automated CI workflows currently include the following tools:

In addition to catching problems, bots will automatically fix any formatting issues. This eliminates the need to configure a complicated local development environment so that you can focus on the code. CI takes the load off your back and points you to any problem areas requiring your attention.

Local development environment

We configured our tools to support those who prefer to perform testing and formatting locally. Jockey uses Poetry to manage the Python development environment.

First, make sure you have Poetry installed. If not, please refer to the Poetry installation guide.

Next, install the dependencies of Jockey using Poetry:

poetry install

Once everything is ready, you can configure your editor to use the Poetry-generated virtual environment or drop into the shell using Poetry:

poetry shell

Check formatting

Jockey uses the following linters to check formatting:

It's possible to run these linters locally:

black
# Lint code format with black
poetry run black src tests --check
isort
# Lint import order with isort
poetry run isort src tests --check
flake8
# Lint with flake8
poetry run flake8 src tests
mypy
# Lint with mypy
poetry run mypy src

Fix formatting

Not only are you able to check your formatting, but a few linters can automatically fix it:

black
# Fix code format with black
poetry run black src
isort
# Fix import order with isort
poetry run isort src tests

Run tests

Jockey uses several unit tests to validate software functionality. You can run these locally, too:

pytest
# Execute unit tests
poetry run pytest -s

Submitting changes

Implementing a fix or a new feature is even more valuable than a great bug report or feature request. Your contributions are precious as the foundation of open-source development.

If your change requires a significant amount of work to write, we recommend starting by opening an issue laying out your plan. That lets a conversation happen early in case other contributors disagree with your plan or have ideas that will help you do it.

We lean on the GitHub pull-request workflow. If you're unfamiliar with this, please refer to GitHub's documentation on the feature.

The best pull requests clearly describe their purpose and changes. New tests, especially in the presence of significant changes or feature implementations, go a long way toward ensuring enduring stability for Jockey.

Once you're ready to submit your changes, open a pull request on the repository against the master branch. The maintainers will review your changes.

Maintainer guidelines

Maintainers should follow these rules when handling pull requests:

  • Wait for tests to finish and pass before merging PRs.
  • Use the "Squash and Merge" strategy to merge PRs.
  • Delete any branches for merged PRs.
  • Edit the final commit message to conform to this format, where (<scope>) is optional: 
    <type>(<scope>): <message>