Contributing

Overview

Getting Started 

We are happy your are even considering helping. We hope this guide makes the process seamless. We really appreciate your help!

If you are new to open source contribution, please checkout Best practices and Tools in our toolbelt.

Note

All command line code is run from the project root except where noted.

Tip

In git clone <forked_repo_https_link.git> , text inside the < >, and the < > get replaced with the appropriate specific text. The < > visually separate the syntax which remains unchanged from the text that needs to be changed. It is a common development pattern that is confusing if you have not seen it before. To see another example of it, type git --help on your command line.

Select an issue 

Look through the open issues and for an issue labelled good first issue or documentation that is unassigned.

Once you have selected an issue, then assign it to yourself by placing the word take as a comment. This will indicate to other contributors that you’re working on the issue. Your goal is to finish the process from self assigning the issue to submitting the initial Pull Request (PR) in less than 2 weeks. This keeps your work from diverging too much from the main branch.

That being said, life happens, we appreciate you however you decide to help. If something comes up, and you need to unassign an issue (place the word remove as a comment) or post that you are still working on it, then that is okay.

Build from the source (First time only)

Go to the repo and click on Fork in the upper right.

Navigate to your fork which will be <you_user_name>/mappymatch . Click on the green Code drop down and copy the https link.
From the command line:
Clone the forked repo.
git clone <forked_repo_https_link.git>
Create the Conda environment, and activate it. You will need to run each command separately.
cd mappymatch
conda env create -f environment_dev.yml
conda activate mappymatch_dev
Verify installation by running tests.
python -m unittest discover
Return should look like this, but the number of tests will vary.
................................................
---------------------------------------------------------------
Ran 51 tests in 14.621s

OK

Install Pre-Commit hooks (First time only)

pre-commit install

Setup Git workflow (First time only)

Setup upstream remote.

git remote add upstream https://github.com/NREL/mappymatch.git

Execute Changes and Git workflow 

Checkout a branch from your forked repository
git checkout -b <descriptive_branch_name>
Make your changes and add commits
Pull in changes from upstream. This is best done periodically, if you have the branch checked out for a long time.
Switch to main branch, pull changes from upstream, resolve conflicts that arise.
git checkout main
git pull upstream main
Switch to your branch, pull the changes from your main repository, and resolve conflicts that arise.
git checkout <descriptive_branch_name>
git pull origin main
Push changes to get ready for PR.
Push your changes to remote for your forked repository.
git push origin <descriptive_branch_name>

Open a PR 

Go to the repo/PR and click on New pull request in the upper right.

Click on Compare across forks in the top middle.

Leave the base repository section alone. For the head repository section select your fork and your branch.

Review the code diffs and then click Create pull request.

Check back after a fewer minutes to make sure the CI steps pass. If they fail, then make the fixes and push your branch to your forked repo again. The PR will update and rerun the CI.

Finish the PR 

Check back in a few days for maintainer requests for changes. Don’t be surprised or offended by the changes. Most PRs require some changes.

Make the changes and push your branch to your forked repo again.

The maintainer will merge your branch.

Delete you branch
Pull the changes into your forked repo.
git checkout main
git pull upstream main

Best practices 

Asking questions 

Have a question? Rather than opening an issue, please ask questions or post comments in Q&A Discussions . Members of the community are happy to assist.

Providing feedback 

Your comments and feedback are very welcome. Please post to General Discussions with lots of detail.

Reporting issues 

We are happy to fix bugs. Please report buys using the issues template.

General issue reporting guidelines 

One issue per problem.

Check through the closed issues before submitting a new one.

Requesting features 

If you are interested in coding or requesting a new feature, let us know in Ideas Discussions Please wait for confirmation from a core maintainer before proceeding.

Previewing documentation locally 

To preview the documentation locally:

From the command line, use Sphinx to rebuild the docs.
sphinx-autobuild -b html ./docs/source ./docs/_build
Open http://127.0.0.1:8000 with your browser.

Maintainer Information 

Adding a new package dependency 

To add a new package dependency, add it to the dependency list in the /pyproject.toml file.

Updating Version Locations 

To update the version automatically using tbump:

tbump <version_major.version_minor.version_patch> --only-patch

To update the version manually update it in the following locations:

In the docs /docs/source/conf.py

In the setup.py /pyproject.toml (2 places)

Releasing to PyPi manually 

Build the wheel
python -m build
Upload to Test PyPi.
twine upload -r testpypi dist/* --verbose
Verify for typos and that the wheel installs. If you spot a mistake, correct it, commit the correction and change the version in the [project] table in /pyproject.toml to <major>.<minor>.<patch>.post<#>

Delete the old wheel, rebuild the wheel and reupload to Test PyPi.

Remove post<#> from the version.
If there are no mistakes, add add tag v<major>.<minor>.<patch> to master branch on github.
Tags have to pushed like a separate branch.
git tag -a v<major>.<minor>.<patch> -m "version <major>.<minor>.<patch>"
git push origin <tagname>
Upload to PyPi.
twine upload dist/*

Tools in our toolbelt 

Note

All command line examples use settings configured for the repo. Coverage and Isort automatically find their configuration files.

Black 

Implemented as a Pre-Commit hook.

Black is an opinionated code formatter so you don’t have to be.

Command line use:

black --config pyproject.toml

Coverage 

Not Implemented as CI

Coverage is a tool used to monitor test coverage. It does so by executing the tests and monitoring which lines are run.

Command line use:

Run the tests with coverage monitoring.

coverage -m unittest discover

View the coverage report.

coverage report -m

Flake8 

Implemented as CI and Pre-Commit hook.

Flake8 is a linting tool that wraps PyFlakes, pycodestyle, and Ned Batchelder’s McCabe script into a single package.

Command Line use:

flake8 --config tox.ini

Interrogate 

Implemented as Pre-Commit hook.

Interrogate reports on the level of and enforces docstring coverage for the code base.

Command line use

interrogate -c pyproject.toml

Isort 

Implemented as Pre-Commit hook.

Isort automatically groups and sorts your import statements so you don’t have to.

Command line use:

isort

Mypy 

Implemented in CI.

Mypy is an optional static type checker for Python that aims to combine the benefits of dynamic (or “duck”) typing and static typing.

Command Line use:

Run normally.

mypy --config-file mypy.ini

Run in verbose mode. Used to see location of specific failures.

mypy --config-file mypy.ini -v

Pre-Commit 

Implements all the precommit hooks.

Pre-Commit is a framework for managing and maintaining multilanguage pre-commit hooks. Before the commit executes, pre-commit hooks are run to do useful things like code formatting. This means the unformatted code never enters your code base.

Command line use:

Run once to install hooks configured by .pre-commit-config.yaml

pre-commit install

Make changes to the code base, add files to the staging area, and commit changes as you normally would.

git commit -m "Updated tools in toolchain docs section."

You will get a success or failure.

Example output for success. No other steps are needed.

black................................................(no files to check)Skipped
isort (python).......................................(no files to check)Skipped
interrogate..........................................(no files to check)Skipped
[create_contributing_docs 30c2bf3] Updated tools in toolchain docs section.
1 file changed, 80 insertions(+), 4 deletions(-)

Example output for failure. See next code block for follow on steps.

black....................................................................Failed
- hook id: black
- files were modified by this hook

reformatted mappymatch\utils\url.py

All done! \u2728 \U0001f370 \u2728
1 file reformatted.

isort (python)...........................................................Passed
interrogate..............................................................Passed

Re-add the files to the staging area. Commit again. You should get a success.

git add --all
git commit -m "Update contributing docs for precommit-failure."