Merge pull request #161 from guilieb/fix/contributing

Review of CONTRIBUTING & Documentation before general availability

Author: HugoPerrier

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,29 +1,50 @@
 ---
 name: Bug report
-about: Create a report to help us improve
+about: Create a report to help us improve Melusine
 title: ''
 labels: 'type:bug'
 assignees: ''
 ---
 
-Hey there and thank you for using Issue Tracker!
+Hey there, and thank you for using Melusine's Issue Tracker!
 
 Do the checklist before filing an issue:
 
-- Is this something you can debug and fix? Send a pull request ! Bug fixes and documentation fixes are welcome.
-- Have a usage question ? Ask your question on StackOverflow. We use StackOverflow for usage question and GitHub for bugs.
+- Is this something you can debug and fix? Send a pull request! Bug fixes and documentation fixes are welcome.
+- Have a usage question? Ask your question on StackOverflow. We use StackOverflow for usage question and GitHub for bugs.
 
-None of the above, create a bug report
+None of the above, create a bug report!
 
 Make sure to add all the information needed to understand the bug so that someone can help. If the info is missing we'll add the 'Needs more information' label and close the issue until there is enough information.
 
+## Instructions
+
 - Provide a minimal code snippet example that reproduces the bug.
-- Provide screenshots where appropriate
-- What's the version of Python you're using ?
-- Are you using Mac, Linux or Windows?
+- Provide screenshots where appropriate.
+- What's the version of Python you're using?
+- Are you using Mac, Linux or Windows? On Linux, provide details about your distribution.
+
+## Debug Information
+
+Please write the debug information inside <code>```</code> quotes in order to prevent text interpretation by the text editor.
+
+**Operating System**: (run `cat /etc/os-release` in a terminal if running on a GNU/Linux distribution)
+
+```
+```
+
+**Python version**: (run `python --version` in the environment running Melusine)
+
+```
+```
+
+**Melusine version**: (run `pip freeze |grep melusine` in your Python environment)
+
+```
+```
 
-**Python version** :
+**Python packages**: (run `pip freeze` in your Python environment)
 
-**Melusine version** :
+```
+```
 
-**Operating System** :

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # How to contribute to Melusine Open source
 
-This guide aims to help you contributing to Melusine. If you have found any problems, improvements that can be done, or you have a burning desire to develop new features for Melusine, please make sure to follow the steps bellow.
+This guide aims to help you contribute to Melusine. If you have found any problems, improvements that can be done, or you have a burning desire to develop new features for Melusine, please make sure to follow the steps bellow.
 
 - [How to open an issue](#how-to-open-an-issue)
 - [Create your contribution to submit a pull request](#create-your-contribution-to-submit-a-pull-request)
@@ -18,14 +18,14 @@ This guide aims to help you contributing to Melusine. If you have found any prob
 
 An issue will open a discussion to evaluate if the problem / feature that you submit is eligible, and legitimate for Melusine.
 
-Check on the project tab if your issue / feature is not already created. In this tab, you will find the roadmap of Melusine.
+Before opening any new issue, check on the project tab if your issue / feature is not already created. We would like to avoid duplicates. In this tab, you will find the roadmap of Melusine.
 
-A Pull Request must be linked to an issue.
-Before you open an issue, please check the current opened issues to insure there are no duplicate. Define if it's a feature or a bugfix.
+A Pull Request must be linked to an issue. Whether it is a bugfix or a feature request, please specify the labels **bug** or **enhancement**.
 
 Next, the Melusine team, or the community, will give you a feedback on whether your issue must be implemented in Melusine, or if it can be resolved easily without a pull request.
 
 # Create your contribution to submit a pull request
+
 ## Fork to code in your personal Melusine repo
 
 The first step is to get our MAIF repository on your personal GitHub repositories. To do so, use the "Fork" button.
@@ -42,96 +42,99 @@ Click on the "Code" button to copy the url of your repository, and next, you can
 git clone https://github.com/YOUR_GITHUB_PROFILE/melusine.git
 ```
 
-## Make sure that your repository is up to date
+## Make sure that your repository is up-to-date
 
-To insure that your local forked repository is synced, you have to update your repo with the master branch of Melusine (MAIF). So, go to your repository and as follow :
+To ensure that your local forked repository is synced with the upstream version available in this repository, you have to update your repo with the `master` branch of Melusine (managed by MAIF). So, go to your repository and as follows:
 
 ```
 cd melusine
 git remote add upstream https://github.com/MAIF/melusine.git
 git pull upstream master
 ```
 
-## Install Melusine into a virtualenv
+## Install Melusine into a Python `virtualenv`
 
-Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
+Install your local Python environment using the `venv` module of recent Python versions. Read the instructions below to build this environment for local deployments:
 
-First create a python virtual environment
+First create a Python virtual environment. Python 3.8+ is required.
 ```
-mkvirtualenv melusine
+python -m venv melusine-pyenv
 ```
-Go in the melusine directory
+
+Activate the environment. This step is required every time you will contribute to the development of Melusine. For more information about Python virtual environments, [read the official documentation](https://docs.python.org/3/library/venv.html). Your environment is next to the Melusine project, stored in the `melusine` directory.
 ```
-cd melusine
+source melusine-pyenv/bin/activate
 ```
-Install you local package
+
+Then, go to the melusine directory and install the local packages.
 ```
-python setup.py develop
+cd melusine
 ```
-or
+
+Then, install the dependencies using `pip`. You can add the `-e` option to keep the last modifications dynamically stored in your virtual env.
 ```
-pip install -e .
+pip install .
 ```
-or to have optionnal dependencies
+
+There are many other targets available to add dependencies: `dev`, `tests`, `transformers`, `docs`. You can install them like:
 ```
-pip install ".[transformers]"
+pip install ".[dev]"
 ```
 
-## Start your contribution code
+## Start your Contribution Code
+
+To contribute to Melusine, you will need to create a personal branch on which you will be responsible for your changes. This means you will have to ensure your tests pass and you only modify the code related to your changes. You have to install the dependencies of the `dev` target.
 
-To contribute to Melusine, you will need to create a personal branch.
 ```
 git checkout -b feature/my-contribution-branch
 ```
-We recommand to use a convention of naming branch.
-- **feature/your_feature_name** if you are creating a feature
-- **hotfix/your_bug_fix** if you are fixing a bug
 
-## Commit your changes
+We recommend to use a convention of naming branch:
+- **feature/your_feature_name** if you are creating a feature.
+- **hotfix/your_bug_fix** if you are fixing a bug.
+
+## Commit Your Changes
 
-Before committing your modifications, we have some recommendations :
+Before committing your modifications, we have some recommendations:
 
-- Execute pytest to check that all tests pass
+- Execute `pytest` to check that all tests pass.
 ```
 pytest
 ```
-- Try to build Melusine
+
+- Try to build Melusine.
 ```
-python setup.py bdist_wheel
+python -m build
 ```
-- Check your code with **flake8**
-
-*We will soon add **pre commit** to automatically check your code quality during commit*
 
+- Use the `pre-commit` configuration.
 ```
-flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-```
+# Installation + auto-configuration of pre-commit
+pip install pre-commit
+pre-commit install
 
-Also for now, try testing tox. It will not be used for much longer as we will be moving to Github Actions and a simpler process soon.
+# Initial run
+pre-commit run --all-files
+```
 
+- Call `tox` to execute more automated tests.
 ```
 tox
 ```
 
-To get flake8 and tox, just pip install them into your virtualenv.
-
-In addition, we recommend committing with clear messages and grouping your commits by modifications dependencies.
+In addition, we recommend committing with clear messages and grouping your commits by modifications dependencies. Read this [GitHub Gist](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53) to have an idea of what we have in mind when speaking of which.
 
 Once all of these steps succeed, push your local modifications to your remote repository.
-
 ```
-git add .
-git commit -m ‘detailed description of your change’
+git add YOUR_FILES_WHAT WHERE_MODIFIED
+git commit
 git push origin feature/my-contribution-branch
 ```
 
-Your branch is now available on your remote forked repository, with your changes.
-
-Next step is now to create a Pull Request so the Melusine Team can add your changes to the official repository.
+Your branch is now available on your remote forked repository, with your changes. Next step is now to create a Pull Request so the Melusine Team can review and merge your changes to the official repository.
 
 ## Create a Pull Request
 
-
 A pull request allows you to ask the Melusine team to review your changes, and merge your changes into the master branch of the official repository.
 
 To create one, on the top of your forked repository, you will find a button "Compare & pull request"
@@ -153,15 +156,14 @@ Once you have selected the right branch, let's create the pull request with the
 
 <img src="https://raw.githubusercontent.com/MAIF/melusine/master/docs/assets/images/contributing/melusine-pr-description.png" alt="clone your forked repository" />
 
-In the description, a template is initialized with all informations you have to give about what you are doing on what your PR is doing.
+In the description, a template is initialized with all information you have to give about what you are doing on what your PR is doing.
 
 Please follow this to write your PR content.
 
-
-## Finally submit your pull request
+## Finally, submit your pull request
 
 Your pull request is now ready to be submitted. A member of the Melusine team will contact you and will review your code and contact you if needed.
 
-You have contributed to an Open source project, thank you and congratulations ! 🥳
+You have contributed to an Open source project, thank you and congratulations! 🥳
 
-Show your contribution to Melusine in your curriculum, and share it on your social media. Be proud of yourself, you gave some code lines to the entire world !
+Show your contribution to Melusine in your curriculum, and share it on your social media. Be proud of yourself, you gave some code lines to the entire world!