Contributing and Maintenance Guide
==================================

Contribution in any form is welcome, including and not limited to code, ideas,
documentation.

If you discovered a bug or have a feature request, please first `open an issue
<https://github.com/brettcannon/gidgethub/issues>`_ before proceeding to
create a pull request for it.

For ideas or general questions about the library, they can be discussed on
`GitHub Discussions <https://github.com/brettcannon/gidgethub/discussions>`_.


Contributing Guide
------------------

Pull request workflow
'''''''''''''''''''''

You don't have to be "assigned" to the issue in order to start working on
a pull request. Ideally the issue has been discussed and agreed first
before you start working on a pull request.

It is recommended that you work on a feature branch, instead of on the main
branch.

Ensure that the tests are all passing, and that the coverage remains at 100%.

Ensure that the code the quality checks by running ``nox --session lint``.

Update the documentation as needed.

Update the changelog as needed.

Preview the documentation on Read the Docs. This gets created as part of the CI
of your pull request.

In your commit message or pull request description, mention the issue, by using
one of the `GitHub-recognized keywords <https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword>`_
like ``closes ...`` or ``fixes ...``.


Maintenance Guide
-----------------

Merging a pull request
''''''''''''''''''''''

Ensure that the tests are all passing, and that the coverage remains at
100% before merging the pull request.

Squash the commits. Rewrite the commit message if necessary.

Documentation build
'''''''''''''''''''

The documentation is hosted at Read the Docs. Documentation build is triggered
immediately after each commit to the main branch.

The up-to-date list of maintainers who can deploy or debug the documentation
build can be seen on the project's `Read the Docs page
<https://readthedocs.org/projects/gidgethub/>`_.

Releasing the library
'''''''''''''''''''''

At the moment there is no fixed release schedule. If you were waiting for an
unreleased feature or bugfix, you can request it to be released
by opening an issue. One of the maintainers can respond and cut a release.

The up-to-date list of maintainers who can cut a release can be seen on the
project's `PyPI page <https://pypi.org/project/gidgethub/>`_.

Pre-release:

- Ensure that the changelog is up-to-date.

- Ensure that the ``__version__`` number in ``gidgethub/__init__.py`` is up to date.

- Ensure the tests have passed and that coverage is at 100%.

Preparing for a release:

- Create a new branch for the release.

- Push the "release" branch to remote.

- Publish the package to PyPI. Use the command ``flit publish`` on the command line.

- `Draft a new release <https://github.com/brettcannon/gidgethub/releases/new>`_
  on GitHub, targeting the "release" branch. Include the changelog, and attach
  the binaries generated by ``flit``.

- Publish the release on GitHub.

Post-release:

- Bump the ``__version__`` number in ``gidgethub/__init__.py`` to include a
  ``.dev`` or a ``.post`` suffix.

- Announce the release. (optional).

