diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c1ef035 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,112 @@ +# Contributing to readchar + +:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: + +The following is a set of guidelines for contributing to this GitHub project. These are mostly guidelines, not rules. Use your best judgment, and feel +free to propose changes to this document in a pull request. + +## Opening an issue + +If you want to open an issue about a problem or bug you encountered, simply go to the GitHub page and click _New issue_ in the _issues_ section. You +will be presented with templates to use, choose a relevant one. (If no template fits, you can open a blank issue. But make sure you input all the +appropriate information!) + +Fill out the template. You should at least provide the following information: + +- a short but exact description of your problem (screenshots often help) +- steps on how to reproduce the problem +- Information about your system: + - your OS + - your Python version and implementation + - the version of readchar you use + +## Opening a pull request + +Follow these steps if you want to contribute code to the project: + +1. Fork this Git repository and create your branch from `master`. + +2. Check out the code to your local machine by following the steps in [Getting the code](#getting-the-code) and make your changes. + +3. **Make sure the tests pass!!** + +4. If you added to the source code, add tests for your new code. + +5. Update the documentation, if necessary. + +6. Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), if you have multiple changes, make sure your + commits are atomic (single irreducible change that makes sense on its own) + +7. Done, you can open a pull request. + +## Getting the code + +If you want to experiment with the code yourself, you can get started by following these steps. + +1. Clone the repository. + + ```bash + git clone https://github.com/magmax/python-readchar.git + ``` + +2. Create a virtual environment: + + ```bash + python -m venv .venv + ``` + +3. Enter the virtual environment + + on Linux systems: + + ```bash + source .venv/bin/activate + ``` + + or for Windows systems: + + ```bash + .venv\Scripts\activate + ``` + +4. Install dependencies + + ```bash + pip install -r requirements.txt + ``` + +5. Install the local version of readchar (in edit mode, so it automatically reflects changes) + + ```bash + pip install -e . + ``` + +### Run the tests! + +Always make sure all tests pass before suggesting any changes! This will avoid invalid PR's. + +The simplest way is to just run `make`. The provided makefile calls all tests for you. + +```bash +make +``` + +If you don't have `make`, you could run all tests manually like this: + +- run `pytest` (source-code testing) + + ```bash + pytest + ``` + +- run `pre-commit` (linting and styling) + + ```bash + pre-commit run -a + ``` + +- run `setup.py` (to test build process) + + ```bash + python setup.py sdist bdist_wheel + ``` diff --git a/README.rst b/README.rst index 83ef061..80877a0 100644 --- a/README.rst +++ b/README.rst @@ -117,58 +117,10 @@ Thank you! How to contribute ================= -You can download the code, make some changes with their tests, and open a pull-request. +You have an issue problem or found a bug? You have a great new idea or just want to fix a typo? Great :+1:. We are happy to accept your issue or pull +request, but first, please read our `contribution guidelines `_. They will also tell you how to write code for this repo and +how to properly prepare an issue or a pull request. -In order to develop and run the tests, follow these steps: - -1. Clone the repository. - - .. code:: bash - - git clone https://github.com/magmax/python-readchar.git - -2. Create a virtual environment: - - .. code:: bash - - python -m venv .venv - -3. Enter the virtual environment - - on Linux systems: - - .. code:: bash - - source .venv/bin/activate - - or for Windows systems: - - .. code:: bash - - .venv\Scripts\activate - -4. Install dependencies - - .. code:: bash - - pip install -r requirements.txt - -5. Install the local version of readchar (in edit mode, so it automatically reflects changes) - - .. code:: bash - - pip install -e . - -6. Run tests - - .. code:: bash - - make - - (or run the commands used inside the Makefile manually, if you don't have/know :code:`make`) - - -Please, **Execute the tests before any pull-request**. This will avoid invalid builds. ------ @@ -201,4 +153,5 @@ Please, **Execute the tests before any pull-request**. This will avoid invalid b .. _GitHub: https://github.com/magmax/python-readchar .. _PyPi: https://pypi.python.org/pypi/readchar .. _LICENCE: LICENCE +.. _CONTRIBUTING: https://github.com/magmax/python-readchar/blob/master/CONTRIBUTING.md .. _python-inquirer: https://github.com/magmax/python-inquirer