From aa389234e83bdbf5c958305d78b81d73cb7c7cda Mon Sep 17 00:00:00 2001 From: vapaunic <15053814+vapaunic@users.noreply.github.com> Date: Thu, 9 Jan 2020 16:15:59 +0000 Subject: [PATCH] Update to CONTRIBUTING instructions (#34) * style checking and formatting files * git hook installation guide * issue and PR templates * minor change * working with github instructions * added specific issue templates * addressed PR comments * addressed Chenhui's comment * addressing chenhuis comments Former-commit-id: d5af35d868b626f4d8b4084076eff5fa4a14ab37 --- .flake8 | 17 ++++++ .github/ISSUE_TEMPLATE.md | 25 ++++++++ .github/ISSUE_TEMPLATE/bug_report.md | 27 +++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 19 ++++++ .github/ISSUE_TEMPLATE/general_ask.md | 14 +++++ .github/PULL_REQUEST_TEMPLATE.md | 15 +++++ .pre-commit-config.yaml | 17 ++++++ CONTRIBUTING.md | 70 ++++++++++++++++++++--- pyproject.toml | 16 ++++++ 9 files changed, 213 insertions(+), 7 deletions(-) create mode 100644 .flake8 create mode 100644 .github/ISSUE_TEMPLATE.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/general_ask.md create mode 100644 .pre-commit-config.yaml create mode 100644 pyproject.toml diff --git a/.flake8 b/.flake8 new file mode 100644 index 00000000..e87fe605 --- /dev/null +++ b/.flake8 @@ -0,0 +1,17 @@ +[flake8] +max-line-length = 120 +max-complexity = 18 +select = B,C,E,F,W,T4,B9 +ignore = + # slice notation whitespace, invalid + E203 + # too many leading ‘#’ for block comment + E266 + # module level import not at top of file + E402 + # line break before binary operator + W503 + # blank line contains whitespace + W293 + # line too long + E501 \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 00000000..8600f409 --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,25 @@ +### Description + + + +### In which platform does it happen? + + + + + + +### How do we replicate the issue? + + + + + + + +### Expected behavior (i.e. solution) + + + + +### Other Comments \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..f9c7e426 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,27 @@ +--- +name: Bug report +about: Create a report to help us improve +title: "[BUG] " +labels: 'bug' +assignees: '' + +--- + +### Description + + + +### How do we replicate the bug? + + + + + + + +### Expected behavior (i.e. solution) + + + + +### Other Comments \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..2f0af6d6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,19 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: "[FEATURE] " +labels: 'enhancement' +assignees: '' + +--- + +### Description + + + +### Expected behavior with the suggested feature + + + + +### Other Comments \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/general_ask.md b/.github/ISSUE_TEMPLATE/general_ask.md new file mode 100644 index 00000000..9c412a2c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/general_ask.md @@ -0,0 +1,14 @@ +--- +name: General ask +about: Technical/non-technical asks about the repo +title: "[ASK] " +labels: '' +assignees: '' + +--- + +### Description + + + +### Other Comments \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e69de29b..e26f0047 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,15 @@ +### Description + + + + +### Related Issues + + + +### Checklist: + + +- [ ] My code follows the code style of this project, as detailed in our [contribution guidelines](../CONTRIBUTING.md). +- [ ] I have added tests. +- [ ] I have updated the documentation accordingly. \ No newline at end of file diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..078edd76 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,17 @@ +repos: +- repo: https://github.com/psf/black + rev: stable + hooks: + - id: black +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v1.2.3 + hooks: + - id: flake8 +- repo: local + hooks: + - id: jupytext + name: jupytext + entry: jupytext --from ipynb --pipe black --check flake8 + pass_filenames: true + files: .ipynb + language: python \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 21518fbb..75d4b1f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,21 +18,77 @@ When you submit a pull request, a CLA-bot will automatically determine whether y Here are the basic steps to get started with your first contribution. Please reach out with any questions. 1. Use [open issues](https://github.com/Microsoft/Forecasting/issues) to discuss the proposed changes. Create an issue describing changes if necessary to collect feedback. Also, please use provided labels to tag issues so everyone can easily sort issues of interest. 2. [Fork the repo](https://help.github.com/articles/fork-a-repo/) so you can make and test local changes. -3. Create a new branch for the issue. We suggest prefixing the branch with your username and then a descriptive title: (e.g. chenhui/python_test_pipeline) -4. Create a test that replicates the issue. +3. Create a new branch for the issue. We suggest prefixing the branch with your username and then a descriptive title, e.g. chenhui/python_test_pipeline. 5. Make code changes. -6. Ensure unit tests pass and code style / formatting is consistent (see [wiki](https://github.com/Microsoft/Forecasting/wiki/Coding-Guidelines#python-and-docstrings-style) for more details). -7. Create a pull request against staging branch. +6. Ensure unit tests pass and code style / formatting is consistent (see [wiki](https://github.com/Microsoft/Recommenders/wiki/Coding-Guidelines#python-and-docstrings-style) for more details). +7. We use [pre-commit](https://pre-commit.com/) package to run our pre-commit hooks. We use [black](https://github.com/ambv/black) formatter and [flake8](https://pypi.org/project/flake8/) for linting on each commit. In order to set up pre-commit on your machine, follow the steps here, please note that you only need to run these steps the first time you use `pre-commit` for this project. + + * Update your conda environment, `pre-commit` is part of the yaml file or just do + ``` + $ pip install pre-commit + ``` + * Set up `pre-commit` by running following command, this will put pre-commit under your .git/hooks directory. + ``` + $ pre-commit install + ``` + > Note: Git hooks to install are specified in the pre-commit configuration file `.pre-commit-config.yaml`. Settings used by `black` and `flake8` are specified in `pyproject.toml` and `.flake8` files, respectively. + * When you've made changes on local files and are ready to commit, run + ``` + $ git commit -m "message" + ``` + * Each time you commit, git will run the pre-commit hooks on any python files that are getting committed and are part of the git index. If `black` modifies/formats the file, or if `flake8` finds any linting errors, the commit will not succeed. You will need to stage the file again if `black` changed the file, or fix the issues identified by `flake8` and and stage it again. -Note: We use the staging branch to land all new features, so please remember to create the Pull Request against staging. To work with GitHub, please see the wiki for more detail about our [github rules](https://github.com/Microsoft/Forecasting/wiki/Rules-to-work-with-GitHub) + * To run pre-commit on all files just run + ``` + $ pre-commit run --all-files + ``` + + +8. Create a pull request (PR) against __`staging`__ branch. + + +We use `staging` branch to land all new features, so please remember to create the Pull Request against `staging`. To work with GitHub, please see the next section for more detail about our [working with GitHub](#working-with-github). + +Once the features included in a milestone are complete we will merge `staging` into `master` branch and make a release. See the wiki for more detail about our [merge strategy](https://github.com/Microsoft/Forecasting/wiki/Strategy-to-merge-the-code-to-master-branch). + +### Working with GitHub + +1. All development is done in a branch off from the `staging` and named following this convention: `/`. +To create a new branch, run this command: + ```shell + $ git checkout -b / + ``` + + When done making the changes locally, push your branch to the server, but make sure to sync with the remote first. + + ``` + $ git pull origin staging + $ git push origin + ``` + +2. To merge a new branch into the `staging` branch, please open a pull request. + +3. The person who opens a PR should complete the PR, once it has been reviewed and all comments addressed. + +4. We will use *Squash and Merge* when completing PRs, to maintain a clean merge history on the repo. + +5. When a branch is merged into the `staging`, it must be deleted from the remote repository. + + ```shell + # Delete local branch + $ git branch -d + + # Delete remote branch + $ git push origin --delete + ``` -Once the features included in a milestone are complete we will merge staging into master and make a release. See the wiki for more detail about our [merge strategy](https://github.com/Microsoft/Forecasting/wiki/Strategy-to-merge-the-code-to-master-branch). ## Coding Guidelines We strive to maintain high quality code to make it easy to understand, use, and extend. We also work hard to maintain a friendly and constructive environment. We've found that having clear expectations on the development process and consistent style helps to ensure everyone can contribute and collaborate effectively. -Please review the [coding guidelines](https://github.com/Microsoft/Forecasting/wiki/Coding-Guidelines) wiki page to see more details about the expectations for development approach and style. +Please review the [coding guidelines](https://github.com/Microsoft/Recommenders/wiki/Coding-Guidelines) wiki page to see more details about the expectations for development approach and style. + ## Code of Conduct diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..e6c68b54 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,16 @@ +[tool.black] +line-length = 120 +include = '\.pyi?$' +exclude = ''' +/( + \.git + | \.hg + | \.mypy_cache + | \.tox + | \.venv + | _build + | buck-out + | build + | dist +)/ +''' \ No newline at end of file