Skip to content

Latest commit

 

History

History
121 lines (97 loc) · 4.56 KB

CONTRIBUTING.rst

File metadata and controls

121 lines (97 loc) · 4.56 KB

Contributing to Graylint

This is a micro project with a small code base, few contributors and hobby maintainership. For this reason, please don't expect immediate responses to bug reports and pull requests. They will all be responded to eventually.

We follow common conventions and code of conduct for Open Source collaboration on GitHub.

Some additional simple guidelines:

Bug reports

Please include

  • release or Git commit for the version of Graylint you're using
  • Python and linter versions
  • your command line
  • file to be linted as an attachment, if possible – also great if squeezed down to a minimal example
  • resulting output or error message
  • expected output

Pull requests

To speed up review and increase odds for the PR to be accepted, please

  • keep all modified code black & isort formatted

  • don't reformat unmodified code

  • include a test case for new or modified code

  • use type hinting

  • make sure the test suite passes

  • verify that mypy static type checking passes

  • document new features or changed behavior in README.rst

  • summarize end-user affecting changes in CHANGES.rst

  • add your information in contributors.yaml

  • contributor information will be updated to CONTRIBUTORS.rst and README.rst in the next release; however, if you have a GitHub personal access token and want to do this yourself, you can run:

    python release_tools/update_contributors.py \
  generate \
  --token=<your GitHub personal access token> \
  --modify-readme \
  --modify-contributors

GitHub is configured to use Github Actions on each pull request to

  • run the test suite using Pytest
  • do static type checking using Mypy
  • lint the code using various linters
  • check code formatting using Black

Creating a GitHub personal access token

Below are the necessary steps to create a GitHub token. You can either go interactively step by step, or start straight at step 6. by clicking on the Generate new token link. For more information, see Creating a fine-grained personal access token in GitHub Docs.

  1. Verify your email address, if it hasn't been verified yet.

  2. In the upper-right corner of any page, click your profile photo, then click Settings.

    https://docs.github.com/assets/cb-34573/images/help/settings/userbar-account-settings.png

  3. In the left sidebar, click Developer settings.

  4. In the left sidebar, under Personal access tokens, click Fine-grained tokens.

  5. Click Generate new token.

  6. Under Token name, enter "Update Graylint contributors".

  7. Under Expiration, select an expiration for the token.

  8. Under Description, type "Allow graylint/release_tools/update_contributors.py to retrieve any user's login, full name and link to avatar picture."

  9. Click Generate token.

  10. Copy and save the token (you won't be able to see it again), and use it on the update_contributors.py command line as shown above.

Setting up a development environment

To set up an isolated virtualenv for Graylint development, modify code in your own branch, run the test suite, and reformat and lint modified code on a Unix-like system:

git clone [email protected]:akaihola/graylint.git
python -m venv .venv-graylint
source .venv-graylint/bin/activate
cd graylint
pip install -e '.[test]'
git checkout -b my-feature-branch
# modify code
git commit -m "My feature"
pytest
darker --config check-graylint.toml

Darker will fix formatting on modified lines and list any linting errors your changes may have introduced compared to the branching point of your feature branch from main: - reformat using Black - sort imports using isort - run Flake8 - run Mypy - run Pydocstyle - run Pylint - run Ruff

Those tools have also been configured to match the conventions in the Graylint code base.