Contributing Guide#

Contributions are what make the open source community such an amazing place to learn, inspire, and create in. Any contributions you make are greatly appreciated!

TL;DR Quickstart#

  1. Have pre-requisites completed:

    • git

    • nox

    • pre-commit

    • Python 3.8+

  2. Fork the project

  3. git clone your fork locally

  4. Create your feature branch (ex. git checkout -b amazing-feature)

  5. Setup your local development environment

    # setup venv
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip setuptools wheel pre-commit nox

# pre-commit configuration
pre-commit install

  6. Hack away!

  7. Commit your changes (ex. git commit -m 'Add some amazing-feature')

  8. Push to the branch (ex. git push origin amazing-feature)

  9. Open a pull request

For the full details, see below.

Ways to contribute#

We value all contributions, not just contributions to the code. In addition to contributing to the code, you can help the project by:

  • Writing, reviewing, and revising documentation, modules, and tutorials

  • Opening issues on bugs, feature requests, or docs

  • Spreading the word about how great this project is

The rest of this guide will explain our toolchain and how to set up your environment to contribute to the project.

Overview of how to contribute to this repository#

To contribute to this repository, you first need to set up your own local repository:

After this initial setup, you then need to:

Once a merge request gets approved, it can be merged!

Prerequisites#

For local development, the following prerequisites are needed:

Windows 10 users#

For the best experience, when contributing from a Windows OS to projects using Python-based tools like pre-commit, we recommend setting up Windows Subsystem for Linux (WSL), with the latest version being WSLv2.

The following gists on GitHub have been consulted with success for several contributors:

We recommend Installing Chocolatey on Windows 10 via PowerShell w/ Some Starter Packages. This installs git, microsoft-windows-terminal, and other helpful tools via the awesome Windows package management tool, Chocolatey.

choco install git easily installs git for a good Windows-dev experience. From the git package page on Chocolatey, the following are installed:

  • Git BASH

  • Git GUI

  • Shell Integration

Fork, clone, and branch the repo#

This project uses the fork and branch Git workflow. For an overview of this method, see Using the Fork-and-Branch Git Workflow.

  • First, create a new fork into your personal user space.

  • Then, clone the forked repo to your local machine.

    # SSH or HTTPS
git clone <forked-repo-path>/idem.git

Note

Before cloning your forked repo when using SSH, you need to create an SSH key so that your local Git repository can authenticate to the GitLab remote server. See GitLab and SSH keys for instructions, or Connecting to GitHub with SSH.

Configure the remotes for your main upstream repository:

# Move into cloned repo
cd idem

# Choose SSH or HTTPS upstream endpoint
git remote add upstream git-or-https-repo-you-forked-from

Create new branch for changes to submit:

git checkout -b amazing-feature

Set up your local preview environment#

If you are not on a Linux machine, you need to set up a virtual environment to preview your local changes and ensure the prerequisites are met for a Python virtual environment.

From within your local copy of the forked repo:

# Setup venv
python3 -m venv .venv
# If Python 3.8+ is in path as 'python', use the following instead:
# python -m venv .venv

# Activate venv
source .venv/bin/activate
# On Windows, use instead:
# .venv/Scripts/activate

# Install required python packages to venv
pip install -U pip setuptools wheel pre-commit nox
pip install -r requirements/base.txt

# Setup pre-commit
pre-commit install

pre-commit and nox Setup#

This project uses pre-commit and nox to make it easier for contributors to get quick feedback, for quality control, and to increase the chance that your merge request will get reviewed and merged.

nox handles Sphinx requirements and plugins for you, always ensuring your local packages are the needed versions when building docs. You can think of it as Make with superpowers.

What is pre-commit?#

pre-commit is a tool that will automatically run local tests when you attempt to make a git commit. To view what tests are run, you can view the .pre-commit-config.yaml file at the root of the repository.

One big benefit of pre-commit is that auto-corrective measures can be done to files that have been updated. This includes Python formatting best practices, proper file line-endings (which can be a problem with repository contributors using differing operating systems), and more.

If an error is found that cannot be automatically fixed, error output will help point you to where an issue may exist.

Sync local master branch with upstream master#

If needing to sync feature branch with changes from upstream master, do the following:

Note

This will need to be done in case merge conflicts need to be resolved locally before a merge to master in the upstream repo.

git checkout master
git fetch upstream
git pull upstream master
git push origin master
git checkout my-new-feature
git merge master

Preview HTML changes locally#

To ensure that the changes you are implementing are formatted correctly, you should preview a local build of your changes first. To preview the changes:

# Activate venv
source .venv/bin/activate
# On Windows, use instead:
# .venv/Scripts/activate

# Generate HTML documentation with nox
nox -e 'docs-html(clean=False)'

# Sphinx website documentation is dumped to docs/_build/html/*
# You can view this locally
# firefox example
firefox docs/_build/html/index.html

Note

If you encounter an error, Sphinx may be pointing out formatting errors that need to be resolved in order for nox to properly generate the docs.

Testing a pop project#

# View all nox targets
nox -l

# Output version of Python activated/available
# python --version OR
python3 --version

# Run appropriate test
# Ex. if Python 3.8.x
nox -e 'tests-3.8'

This project is a pop project which makes use of pytest-pop, a pytest plugin. For more information on pytest-pop, and writing tests for pop projects:

Contribution Guidelines#

Before asking for a final review for a PR into an idem project, the following guidelines must be met:

Tests#

  • Tests are written for changes

  • Tests provide full coverage of the changed code

Documentation#

  • Docs are written for feature changes

  • Functions have Typehinted parameters

  • Code is sufficiently documented with comments

  • Parameters are explained in detail in function docstrings

  • rst-style examples of the function’s usage are included in its docstring

Code Style#

  • Code is readable and contains comments

  • Code contains sufficient logging, including debug logging

  • Errors are descriptive

  • Follow POP best practices - Plugins are used instead of Classes wherever possible - POP code is accessed via the hub, not python import - Output with hub.log.debug() not print() - The hub is not explicitly passed to functions - Code is organized in the filesystem in a meaningful way - There are no long files - code is separated into plugins with meaningful names (no massive utils.py file) - Plugins are organized in a way that will be easily merged with other projects - Subsystems have contracts to standardize plugin structure - ctx.test must be implemented in idem states

  • Code is written in a re-usable way

Issues#

When reporting a bug, the following criteria should be met:

  • Bugs include complete steps to reproduce including

    • Bugs include a version report from pip freeze

    • Bugs include the full cli command used to reach the error

    • Bugs include sanitized supporting sls/credential files

    • Bugs include output with --log-level=debug logging

    • Bugs include the full error output

Pull Requests#

  • All TODOs are resolved

  • All comments by maintainers in code-review are marked “resolved” by maintainers

  • All existing tests are passing in the PR pipeline

  • The origin pipeline has all tests enabled

  • The origin pipeline is visible to maintainers

Versioning#

  • Backwards-incompatible changes get a major version bump

  • New features get a minor version bump

  • Bugfixes get a point version bump