From e5e5c2b8b67ae615a6f5407bd53916a0a5a53b8a Mon Sep 17 00:00:00 2001 From: JP-Ellis Date: Wed, 20 Sep 2023 18:00:19 +1000 Subject: [PATCH 1/3] docs: rewrite contributing.md This commit rewrites the contributing.md file to be up to date with the current state of the project. It draws heavily from the `CONTRIBUTING.md` file in the [Docusaurus](https://github.com/facebook/docusaurus) project. Signed-off-by: JP-Ellis --- CONTRIBUTING.md | 215 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 158 insertions(+), 57 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 78d6b3c2a..ff77b77bb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,86 +1,187 @@ -# Raising issues +# Contributing to Pact Python -_Before raising an issue, please ensure that you are using the latest version of pact-python._ +Pact Python is the Python implementation of the [Pact](https://pact.io) integration testing framework. If you're interested in contributing to Pact Python, hopefully, this document makes the process for contributing clear. -Please provide the following information with your issue to enable us to respond as quickly as possible. +The [Open Source Guides](https://opensource.guide/) website has a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to an open source project. Contributors and people new to open source alike will find the following guides especially useful: -- The relevant versions of the packages you are using. -- The steps to recreate your issue. -- The full stacktrace if there is an exception. -- An executable code example where possible. You can fork this repository and - use the [examples] directory to quickly recreate your issue. +- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) +- [Building Welcoming Communities](https://opensource.guide/building-community/) -# Contributing +## Get Involved -1. Fork it -2. Create your feature branch (`git checkout -b my-new-feature`) -3. Commit your changes (`git commit -am 'Add some feature'`) -4. Push to the branch (`git push origin my-new-feature`) -5. Create new Pull Request +There are many ways to contribute to Pact Python and the broader Pact ecosystem. Here's a few ideas to get started: -If you are intending to implement a fairly large feature we'd appreciate if you open -an issue with GitHub detailing your use case and intended solution to discuss how it -might impact other work that is in flight. +- Look through the [open issues](https://github.com/pact-foundation/pact-python/issues). Provide workarounds, ask for clarification, or suggest labels. Help [triage issues](#triaging-issues-and-pull-requests). +- If you find an issue you would like to fix, [open a pull request](#pull-requests). Issues tagged as [_Good first issue_](https://github.com/pact-foundation/pact-python/labels/Good%20first%20issue) are a good place to get started. +- Read through the [docs](https://docs.pact.io). If you find anything that is confusing or can be improved, you can click "Edit this page" at the bottom of most docs, which takes you to the GitHub interface to make and propose changes. +- Take a look at the [features requested](https://github.com/pact-foundation/pact-python/labels/feature) by others in the community and consider opening a pull request if you see something you want to work on. -We also appreciate it if you take the time to update and write tests for any changes -you submit. +Contributions are very welcome. If you think you need help planning your contribution, please ping us on [Slack](https://slack.pact.io) and let us know you are looking for a bit of help. -[examples]: https://github.com/pact-foundation/pact-python/tree/master/examples +### Join our Slack -## Commit messages +We have a [Slack](https://slack.pact.io) to discuss all things about Pact and its development. Feel free to ask questions about Pact Python specifically in the [`#pact-python`](https://pact-foundation.slack.com/archives/C9VECUP6E) channel, or broader questions about the Pact ecosystem over in the [`#general`](https://pact-foundation.slack.com/archives/C5F4KFKR8) channel. -pact-python is adopting the [Conventional Commits](https://www.conventionalcommits.org) -convention. Please ensure you follow the guidelines, we don't want to be that person, -but the commit messages are very important to the automation of our release process. +### Triaging Issues and Pull Requests -Take a look at the git history (`git log`) to get the gist of it. +One great way you can contribute to the project without writing any code is to help triage issues and pull requests as they come in. -If you'd like to get some CLI assistance there is a node npm package. Example usage is: +- Ask for more information if you believe the issue does not provide all the details required to solve it. +- Suggest [labels](https://github.com/pact-foundation/pact-python/labels) that can help categorize issues. +- Flag issues that are stale or that should be closed. +- Ask for test plans and review code. -```shell -npm install -g commitizen -npm install -g cz-conventional-changelog -echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc -``` +## Our Development Process -When you commit with Commitizen, you'll be prompted to fill out any required -commit fields at commit time. Simply use `git cz` or just `cz` instead of -`git commit` when committing. You can also use `git-cz`, which is an alias -for `cz`. +Pact Python uses [GitHub](https://github.com/pact-foundation/pact-python) as its source of truth. The team will be working directly there. All changes will be public from the beginning. -See https://www.npmjs.com/package/commitizen for more info. +All pull requests will be checked by the continuous integration system, GitHub actions. There are unit tests, end-to-end tests, performance tests, style tests, and much more. -There is a pypi package that does similar [commitizen](https://pypi.org/project/commitizen/). +### Branch Organization -## Running the tests +Pact Python has one primary branch `master` and we use feature branches to deliver new features with pull requests. We use the following naming convention for branches: -You can run the tests locally with `make test`, this will run the tests with `tox` +- `feature/` or `feat/` for new features +- `fix/` for bug fixes +- `chore/` for chores +- `docs/` for documentation changes -You will need `pyenv` to test on different versions `3.6`, `3.7`, `3.8`, `3.9`, -`3.10`, `3.11`. +These generally follow the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) categories. -Download and install python versions: -``` -pyenv install 3.6.15 3.7.16 3.8.16 3.9.16 3.10.10 3.11.2 -``` +## Issues -Set these versions locally for the project: -``` -pyenv local 3.6.15 3.7.16 3.8.16 3.9.16 3.10.10 3.11.2 -``` +When [opening a new issue](https://github.com/pact-foundation/pact-python/issues/new/choose), always make sure to fill out the issue template. **This step is very important!** Not doing so may slow down the response. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template. + +**Please don't use the GitHub issue tracker for questions.** If you have questions about using Pact Python, prefer the [Discussion pages](https://github.com/pact-foundation/pact-python/discussions) or [Slack](https://slack.pact.io), and we will do our best to answer your questions. + +### Bugs + +We use [GitHub Issues](https://github.com/pact-foundation/pact-python/issues) for our public bugs. If you would like to report a problem, take a look around and see if someone already opened an issue about it. If you are certain this is a new, unreported bug, you can submit a [bug report](https://github.com/pact-foundation/pact-python/issues/new?assignees=&labels=bug%2Cstatus%3A+needs+triage&template=bug.yml). + +- **One issue, one bug:** Please report a single bug per issue. +- **Provide reproduction steps:** List all the steps necessary to reproduce the issue. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort. + +If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend filing an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue. + +### Feature requests + +If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can file an issue with the [feature template](https://github.com/pact-foundation/pact-python/issues/new?assignees=&labels=feature%2Cstatus%3A+needs+triage&template=feature.yml) for more thought out ideas. Alternatively, you can use the [Canny board](https://pact.canny.io/) for more casual feature requests and gain enough traction before proposing an RFC. + +### Claiming issues + +We have a list of [beginner-friendly issues](https://github.com/pact-foundation/pact-python/labels/good%20first%20issue) to help you get your feet wet in the Pact Python codebase and familiar with our contribution process. This is a great place to get started. + +Apart from the `good first issue`, it is also worth looking at the [`help wanted`](https://github.com/pact-foundation/pact-python/labels/help%20wanted) issues. If you have specific knowledge in one domain, working on these issues can make your expertise shine. + +If you want to work on any of these issues, just drop a message saying "I'd like to work on this", and we will assign the issue to you and update the issue's status as "claimed". + +Alternatively, when opening an issue, you can also click the "self service" checkbox to indicate that you'd like to work on the issue yourself, which will also make us see the issue as "claimed". + +## Development + +### Online one-click setup for contributing + +You can also try using the new [github.dev](https://github.dev/pact-foundation/pact-python) feature. While you are browsing any file, changing the domain name from `github.com` to `github.dev` will turn your browser into an online editor. You can start making changes and send pull requests right away. + +### Installation + +1. Ensure you have [Python](https://www.python.org/) installed. + +2. Ensure you have [Hatch](https://hatch.pypa.io/) installed. This is used to manage the development environment can be installed as follows: + + ```sh + python -m pip install --user pipx # If you don't have pipx + pipx install hatch + ``` + +3. After cloning the repository, run `hatch shell` in the root of the repository. This will install all dependencies in a Python virtual environment and then ensure that the virtual environment is activated. + +4. To run tests, run `hatch run test` to make sure the test suite is working. You should also make sure the example works by running `hatch run example`. For the examples, you will have to make sure that you have Docker (or a suitable alternative) installed and running. + +5. If you want to run the tests against all supported Python versions, you can run `hatch run test:all`. + +### Code Conventions -Run the tests: +- **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming files, naming things in code, naming things in documentation, etc. +- "Attractive" +- We do have Black (a formatter) and Ruff (a syntax linter) to catch most stylistic problems. If you are working locally, they should automatically fix some issues during git commits and push. + +Don't worry too much about styles in generalโ€”the maintainers will help you fix them as they review your code. + +To help catch a lot of simple formatting or linting issues, you can run `hatch run lint` to run Black and Ruff. This process can also be automated by installing [`pre-commit`](https://pre-commit.com/) hooks: + +```sh +pre-commit install ``` -make test + +## Pull Requests + +So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at. + +Working on your first Pull Request? You can learn how from this free video series: + +[**How to Contribute to an Open Source Project on GitHub**](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github) + +Please make sure the following is done when submitting a pull request: + +1. **Keep your PR small.** Small pull requests (~300 lines of diff) are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. +2. **Use descriptive titles.** It is recommended to follow this [commit message style](#semantic-commit-messages). +3. **Test your changes.** Describe your [**test plan**](#test-plan) in your pull request description. + +All pull requests should be opened against the `master` branch. + +We have a lot of integration systems that run automated tests to guard against mistakes. The maintainers will also review your code and fix obvious issues for you. These systems' duty is to make you worry as little about the chores as possible. Your code contributions are more important than sticking to any procedures, although completing the checklist will surely save everyone's time. + +### Conventional Commit Messages + +Pact Python has adopted the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) convention and we use it to generate our changelog and in the automation of our release process. + +The format is: + +```text +(): ``` -### macOS Setup Guide +`` is optional. If your change is specific to one/two packages, consider adding the scope. Scopes should be brief but recognizable, e.g. `docs`, `ci`, etc. You can take a quick look at the Git history (`git log`) to get the gist. + +The various types of commits: + +- `feat`: a new API or behavior **for the end user**. +- `fix`: a bug fix **for the end user**. +- `docs`: a change to the website or other Markdown documents in our repo. +- `style`: a change to production code that leads to no behavior difference, e.g. splitting files, renaming internal variables, improving code style... +- `test`: adding missing tests, refactoring tests; no production code change. +- `chore`: upgrading dependencies, releasing new versions... Chores that are **regularly done** for maintenance purposes. +- `misc`: anything else that doesn't change production code and doesn't fit in the above. + +If you'd like to get some CLI assistance, you can install [commitizen](https://www.npmjs.com/package/commitizen). The `cz` command line tool will help you write conventional commit messages. + +### Test Plan + +A good test plan has the exact commands you ran and their output. + +Tests are integrated into our continuous integration system, so you don't always need to run local tests. However, for significant code changes, it saves both your and the maintainers' time if you can do exhaustive tests locally first to make sure your PR is in good shape. There are many types of tests: -See the following guides to setup Python and configure `pyenv` on your Mac. +- **Build and typecheck.** We use [mypy](https://mypy.readthedocs.io/en/stable/) in our codebase, which can make sure your code is consistent and catches some obvious mistakes early. +- **Unit tests.** We use [pytest](https://pytest.org) for unit tests. You can run `hatch run test` in the root directory to run all tests, and `hatch run test:all` to test against all supported Python versions. -- [How to Install Python on macOS](https://realpython.com/installing-python/#how-to-install-python-on-macos) -- [Managing Multiple Python Versions With pyenv](https://realpython.com/intro-to-pyenv/) +### Licensing + +By contributing to Pact Python, you agree that your contributions will be licensed under its MIT license. + +### Breaking Changes + +When adding a new breaking change, follow this template in your pull request: + +```md +### New breaking change here + +- **Who does this affect**: +- **How to migrate**: +- **Why make this breaking change**: +- **Severity (number of people affected x effort)**: +``` -## Running the examples +### What Happens Next? -Make sure you have docker running! +The team will be monitoring pull requests. Do help us by keeping pull requests consistent by following the guidelines above. From 23ed629cdec0bb0494c802db06984d328f891376 Mon Sep 17 00:00:00 2001 From: JP-Ellis Date: Wed, 20 Sep 2023 18:04:43 +1000 Subject: [PATCH 2/3] docs: add issue and pr templates Along with the overhaul of the `CONTRIBUTING.md` file, this commit adds issue and PR templates to the repository. These templates have been heavily inspired by the [Docusaurus](https://github.com/facebook/docusaurus) project. Signed-off-by: JP-Ellis --- .github/ISSUE_TEMPLATE/bug.yml | 114 +++++++++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 14 ++++ .github/ISSUE_TEMPLATE/feature.yml | 54 ++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 24 ++++++ 4 files changed, 206 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 000000000..e56f7cdec --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,114 @@ +name: ๐Ÿ› Bug Report +description: Submit a bug report to help us improve +labels: [bug, triage] +body: + - type: markdown + attributes: + value: | + ## Please help us help you! + + Before filing your issue, ask yourself: + + - Is this clearly a Pact Python bug? + - Do I have basic ideas about where it goes wrong? + - Could it be because of my own mistakes? + + **The GitHub issue tracker is not a support forum**. If you are not sure whether it could be your mistakes, ask on [Slack](https://slack.pact.io). + + Make the bug obvious. Ideally, we should be able to understand it without running any code. + + Bugs are fixed faster if you include: + - A reproduction repository to replicate the issue + - Pact files + - Logs + + - type: checkboxes + attributes: + label: Have you read the Contributing Guidelines on issues? + options: + - label: I have read the [Contributing Guidelines on issues](https://github.com/pact-foundation/pact-python/main/CONTRIBUTING.md#issues). + required: true + + - type: checkboxes + attributes: + label: Prerequisites + description: Please check the following items before creating a issue. This way we know you've done these steps first. + options: + - label: I'm using the latest version of `pact-python`. + required: true + - label: I have read the console error message carefully (if applicable). + + - type: textarea + attributes: + label: Description + description: A clear and concise description of what the bug is. + validations: + required: true + + - type: input + attributes: + label: Reproducible demo + description: | + Paste the link to an example repo if possible, and exact instructions to reproduce the issue. + + > **What happens if you skip this step?** Someone will read your bug report, and maybe will be able to help you, but it's unlikely that it will get much attention from the team. Eventually, the issue will likely get closed in favor of issues that have reproducible demos. + + Please remember that: + + - Issues without reproducible demos have a very low priority. + - The person fixing the bug would have to do that anyway. Please be respectful of their time. + - You might figure out the issues yourself as you work on extracting it. + + Thanks for helping us help you! + + - type: textarea + attributes: + label: Steps to reproduce + description: Write down the steps to reproduce the bug. You should start with a fresh installation, or your git repository linked above. + placeholder: | + 1. Step 1... + 2. Step 2... + 3. Step 3... + validations: + required: true + + - type: textarea + attributes: + label: Expected behavior + description: How did you expect your project to behave? It's fine if you're not sure your understanding is correct. Write down what you thought would happen. + placeholder: Write what you thought would happen. + validations: + required: true + + - type: textarea + attributes: + label: Actual behavior + description: | + Did something go wrong? Is something broken, or not behaving as you expected? Describe this section in detail. Don't only say "it doesn't work"! Please submit exhaustive and complete log messages, not just the final error message. + + > Please read error messages carefully: it often tells you exactly what you are doing wrong. + + If the logs are too long, you can paste them in a [gist](https://gist.github.com/) and link it here. + placeholder: | + Write what happened. Add full console log messages. + validations: + required: true + + - type: textarea + attributes: + label: Your environment + description: Include as many relevant details about the environment you experienced the bug in. + value: | + - Public source code: + - Pact Python version used: `pip list | grep pact` + - Operating system and version (e.g. Ubuntu 20.04.2 LTS, macOS Ventura): + + - type: checkboxes + attributes: + label: Self-service + description: | + If you feel like you could contribute to this issue, please check the box below. This would tell us and other people looking for contributions that someone's working on it. + + If you do check this box, please send a pull request. If circumstances change and you can't work on it anymore, let us know and we can re-assign it. + options: + - label: I'd be willing to fix this bug myself. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..7c09cc37b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,14 @@ +blank_issues_enabled: false +contact_links: + - name: ๐Ÿš€ Feature request + url: https://pact.canny.io + about: The Canny board to send us feature requests, vote and measure the interest of users. Useful to submit a feature request when you have an idea but no concrete API design proposal. + - name: โ“ Simple question - Slack chat + url: https://slack.pact.io + about: If you have a simple question, or want to discuss a feature request, join our Slack chat. + - name: โ“ Simple question - Stack Overflow + url: https://stackoverflow.com/questions/tagged/pact + about: The GitHub issue tracker is not for technical support. Please use Stack Overflow, and ask the community for help. + - name: โ“ Advanced question - GitHub Discussions + url: https://github.com/pact-foundation/pact-python/discussions + about: Use GitHub Discussions for advanced and unanswered questions only, requiring a maintainer's answer. Make sure the question wasn't already asked. diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 000000000..a27030432 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,54 @@ +name: ๐Ÿ’… Feature design / RFC +description: Submit a detailed feature request with a concrete proposal +labels: [feature, triage] +body: + - type: markdown + attributes: + value: | + Important things: + + - We expect the feature request to be detailed. + - The request does not have to be perfect, we'll discuss it and fix it if needed. + - For a more "casual" feature request, consider using Canny instead: https://pact.canny.io. + + - type: checkboxes + attributes: + label: Have you read the Contributing Guidelines on issues? + options: + - label: I have read the [Contributing Guidelines on issues](https://github.com/pact-foundation/pact-python/blob/main/CONTRIBUTING.md#issues). + required: true + + - type: textarea + attributes: + label: Description + description: A clear and concise description of what the feature is. + validations: + required: true + + - type: input + attributes: + label: Has this been requested on Canny? + description: Please post the [Canny](https://pact.canny.io) link, it is helpful to see how much interest there is for this feature. + + - type: textarea + attributes: + label: Motivation + description: Please outline the motivation for the proposal and why it should be implemented. Has this been requested by a lot of users? + validations: + required: true + + - type: textarea + attributes: + label: Have you tried building it? + description: | + Please explain how you tried to build the feature by yourself, and how successful it was. If you haven't tried, that's alright. + + - type: checkboxes + attributes: + label: Self-service + description: | + If you answered the question above as "no" because you feel like you could contribute directly to our repo, please check the box below. This would tell us and other people looking for contributions that someone's working on it. + + If you do check this box, please send a pull request. If circumstances change and you can't work on it anymore, let us know and we can re-assign it. + options: + - label: I'd be willing to contribute this feature to Docusaurus myself. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..cbc0068bf --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,24 @@ + + +## Pre-flight checklist + +- [ ] I have read the [Contributing Guidelines on pull requests](https://github.com/pact-foundation/pact-python/blob/main/CONTRIBUTING.md#pull-requests). +- [ ] **If this is a code change**: I have written unit tests and/or added dogfooding pages to fully verify the new behavior. +- [ ] **If this is a new API or substantial change**: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan. + +## Motivation + + + +## Test Plan + + + +## Related issues/PRs + + From 000f1a33938b37b5ff63938a3837f4493dde1cfc Mon Sep 17 00:00:00 2001 From: JP-Ellis Date: Fri, 22 Sep 2023 11:37:22 +1000 Subject: [PATCH 3/3] docs: incorporate suggestions from @YOU54F Signed-off-by: JP-Ellis --- .github/ISSUE_TEMPLATE/bug.yml | 7 +++++-- .github/PULL_REQUEST_TEMPLATE.md | 21 +++++++++++++++++---- CONTRIBUTING.md | 23 +++++++++++++++-------- 3 files changed, 37 insertions(+), 14 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index e56f7cdec..be7292c2a 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -9,11 +9,12 @@ body: Before filing your issue, ask yourself: + - Has this bug already been reported? - Is this clearly a Pact Python bug? - Do I have basic ideas about where it goes wrong? - - Could it be because of my own mistakes? + - Could it be because of something on my end? - **The GitHub issue tracker is not a support forum**. If you are not sure whether it could be your mistakes, ask on [Slack](https://slack.pact.io). + **The GitHub issue tracker is not a support forum**. If you are not sure whether it could be on your end or within Pact Python, ask on [Slack](https://slack.pact.io). Make the bug obvious. Ideally, we should be able to understand it without running any code. @@ -100,7 +101,9 @@ body: description: Include as many relevant details about the environment you experienced the bug in. value: | - Public source code: + - Is this a consumer or provider issue? Do you have information about the other side? - Pact Python version used: `pip list | grep pact` + - Information about your Pact broker (version, hosted where, pactflow, ...) - Operating system and version (e.g. Ubuntu 20.04.2 LTS, macOS Ventura): - type: checkboxes diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index cbc0068bf..f43b17a19 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -5,20 +5,33 @@ You can learn more about contributing to Pact-python here: https://github.com/pa Happy contributing! --> -## Pre-flight checklist +## :airplane: Pre-flight checklist - [ ] I have read the [Contributing Guidelines on pull requests](https://github.com/pact-foundation/pact-python/blob/main/CONTRIBUTING.md#pull-requests). - [ ] **If this is a code change**: I have written unit tests and/or added dogfooding pages to fully verify the new behavior. - [ ] **If this is a new API or substantial change**: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan. -## Motivation +## :memo: Summary + + + +## :rotating_light: Breaking Changes + + + +## :fire: Motivation -## Test Plan +## :hammer: Test Plan -## Related issues/PRs +## :link: Related issues/PRs diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff77b77bb..4b6ca493c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,7 @@ The [Open Source Guides](https://opensource.guide/) website has a collection of - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) - [Building Welcoming Communities](https://opensource.guide/building-community/) +- [Contributing to Pact](https://docs.pact.io/contributing) ## Get Involved @@ -18,9 +19,11 @@ There are many ways to contribute to Pact Python and the broader Pact ecosystem. Contributions are very welcome. If you think you need help planning your contribution, please ping us on [Slack](https://slack.pact.io) and let us know you are looking for a bit of help. -### Join our Slack +### Join our Community -We have a [Slack](https://slack.pact.io) to discuss all things about Pact and its development. Feel free to ask questions about Pact Python specifically in the [`#pact-python`](https://pact-foundation.slack.com/archives/C9VECUP6E) channel, or broader questions about the Pact ecosystem over in the [`#general`](https://pact-foundation.slack.com/archives/C5F4KFKR8) channel. +We have a [Slack](https://slack.pact.io) to discuss all things about Pact and its development. Feel free to ask questions about Pact Python specifically in the [`#pact-python`](https://pact-foundation.slack.com/archives/C9VECUP6E) channel, or broader questions about the Pact ecosystem over in the [`#general`](https://pact-foundation.slack.com/archives/C5F4KFKR8) channel. We store a searchable archive of our Slack channels on [linen.dev](https://linen.dev/s/pact-foundation). + +Questions have also been asked over on StackOverflow, under the [`pact`](https://stackoverflow.com/questions/tagged/pact) tag. This is a great place to ask more general usage questions for pact, and discover existing answers. ### Triaging Issues and Pull Requests @@ -39,15 +42,13 @@ All pull requests will be checked by the continuous integration system, GitHub a ### Branch Organization -Pact Python has one primary branch `master` and we use feature branches to deliver new features with pull requests. We use the following naming convention for branches: +Pact Python has one primary branch `master` and we use feature branches to deliver new features with pull requests. Typically, we scope the branch according to the [conventional commit](#conventional-commit-messages) categories. The more common ones are: - `feature/` or `feat/` for new features - `fix/` for bug fixes - `chore/` for chores - `docs/` for documentation changes -These generally follow the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) categories. - ## Issues When [opening a new issue](https://github.com/pact-foundation/pact-python/issues/new/choose), always make sure to fill out the issue template. **This step is very important!** Not doing so may slow down the response. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template. @@ -77,11 +78,15 @@ If you want to work on any of these issues, just drop a message saying "I'd like Alternatively, when opening an issue, you can also click the "self service" checkbox to indicate that you'd like to work on the issue yourself, which will also make us see the issue as "claimed". +Once an issue is claimed, we hope to see a pull request; however we understand that life happens and you may not be able to complete the issue. If you are unable to complete the issue, please let us know so we can unassign the issue and make it available for others to work on. + +The claiming process is there to help ensure effort is wasted. Even if you are not sure whether you can complete the issue, claiming it will help us know that someone is working on it. If you are not sure how to proceed, feel free to ask for help. + ## Development ### Online one-click setup for contributing -You can also try using the new [github.dev](https://github.dev/pact-foundation/pact-python) feature. While you are browsing any file, changing the domain name from `github.com` to `github.dev` will turn your browser into an online editor. You can start making changes and send pull requests right away. +You can also try using the new [github.dev](https://github.dev/pact-foundation/pact-python) feature. While you are browsing any file, changing the domain name from `github.com` to `github.dev` will turn your browser into an online editor. You can start making changes and send pull requests right away. This is a great way to get started quickly, but it does not offer the full development environment and you won't be able to run tests. ### Installation @@ -116,7 +121,9 @@ pre-commit install ## Pull Requests -So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at. +So you are considering contributing to Pact Python's code? Great! We'd love to have you. First off, please make sure it is related to an existing issue. If not, please open a new issue to discuss the problem you are trying to solve before investing a lot of time into a pull request. While we do accept PRs that are not related to an issue (especially if the PR is very simple), it is best to discuss it first to avoid wasting your time. + +Once you have opened a PR, we will do our best to work with you and get the PR looked at. Working on your first Pull Request? You can learn how from this free video series: @@ -130,7 +137,7 @@ Please make sure the following is done when submitting a pull request: All pull requests should be opened against the `master` branch. -We have a lot of integration systems that run automated tests to guard against mistakes. The maintainers will also review your code and fix obvious issues for you. These systems' duty is to make you worry as little about the chores as possible. Your code contributions are more important than sticking to any procedures, although completing the checklist will surely save everyone's time. +We have a lot of integration systems that run automated tests to guard against mistakes. The maintainers will also review your code and may fix obvious issues for you. These systems' duty is to make you worry as little about the chores as possible. Your code contributions are more important than sticking to any procedures, although completing the checklist will surely save everyone's time. ### Conventional Commit Messages