From f53c66ccee6fab9173b49389e86aec27aa12e882 Mon Sep 17 00:00:00 2001 From: Tarek Allam Date: Wed, 8 May 2019 18:31:19 +0100 Subject: [PATCH 1/6] Rename conventions_for_pushes.md to CONTRIBUTING.md Moving file to top level of repo to be a single file that describes how users can contribute to the snmachine project --- docs/contributing/conventions_for_pushes.md => CONTRIBUTING.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/contributing/conventions_for_pushes.md => CONTRIBUTING.md (100%) diff --git a/docs/contributing/conventions_for_pushes.md b/CONTRIBUTING.md similarity index 100% rename from docs/contributing/conventions_for_pushes.md rename to CONTRIBUTING.md From 83d4eaaa55c4546a225d0a5c12dbfb89308ba303 Mon Sep 17 00:00:00 2001 From: Tarek Allam Date: Thu, 9 May 2019 11:16:06 +0100 Subject: [PATCH 2/6] Adding Github ISSUE/PR templates These files allow for templating of issues and pull requests on Github for easier contributions. The layout is akin to: https://github.com/tallamjr/dotfiles/issues/new/choose where one chooses an issue option, BUG, FEATURE_REQUEST, or just make a general issue. In addition, a PULL_REQUEST_TEMPLATE has been created to allow for consistent documentation of what a PR achieves. Fixes #126 --- .github/ISSUE_TEMPLATE/BUG.md | 35 +++++++++++++++++++++++ .github/ISSUE_TEMPLATE/FEATURE_REQUEST.md | 20 +++++++++++++ .github/ISSUE_TEMPLATE/GENERAL.md | 8 ++++++ .github/PULL_REQUEST_TEMPLATE.md | 26 +++++++++++++++++ 4 files changed, 89 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/BUG.md create mode 100644 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.md create mode 100644 .github/ISSUE_TEMPLATE/GENERAL.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/BUG.md b/.github/ISSUE_TEMPLATE/BUG.md new file mode 100644 index 00000000..b74c8f81 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/BUG.md @@ -0,0 +1,35 @@ +--- +name: Bug +about: Report an error or program crash +title: "[BUG]" +labels: bug +assignees: '' + +--- + +**Describe the issue** +_A short description of what the issue is_ + +**Expected behaviour** +_What you expected to happen_ + +**Actual behaviour** +_What actually happened, error messages go here_ + +**To Reproduce** +_Steps to reproduce the behaviour:_ +1. +2. +... + +**System Information:** +_Please update accordingly_ + - Operating System: [`macOS-10.14.14`]: + - `snmachine` Version: [`0.1.0`] + - Occurred on which branch and with what commit: [`master-abc456d`] + +**Screenshots** +_If applicable, add screenshots to help explain your problem_ + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md new file mode 100644 index 00000000..52d6f630 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md @@ -0,0 +1,20 @@ +--- +name: Feature Request +about: Suggest an idea for this project +title: '[FEATURE]' +labels: 'feature' +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/GENERAL.md b/.github/ISSUE_TEMPLATE/GENERAL.md new file mode 100644 index 00000000..19afd52a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/GENERAL.md @@ -0,0 +1,8 @@ +--- +name: General +about: General issue +title: +labels: +assignees: '' + +--- diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..920225eb --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,26 @@ +**IMPORTANT: Please create an issue first before opening a Pull Request.** +Linked to issue(s): _put link_ + +## Type of change + +Please delete options that are not relevant. + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] This change requires a documentation update + +## What changes were proposed in this pull request? + + + +How is the issue this PR is referenced against solved with this PR? + +## How was this patch tested? + +## Final Checklist: + +- [ ] My code follows the style guidelines of this project +- [ ] I have made corresponding changes to the documentation +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] I am up to date with `dev` branch via `git rebase dev` at the time of this PR From 400a9cbf62063850f6b556cd25258226801d7054 Mon Sep 17 00:00:00 2001 From: Tarek Allam Date: Thu, 9 May 2019 14:08:50 +0100 Subject: [PATCH 3/6] Major updates to CONTRIBUTING.md file In addition to Code Style section, further subsections have been added such as: * Creating an Issue * Submitting a Pull Request * Running Tests Locally * Package Versioning Some sections anticipate adoption of certain practises that have not been implemented yet, such as CHANGELOG, but this should be in place in due course. Therefore this commit links to #129 Closes #127 --- CONTRIBUTING.md | 124 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 118 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 09510103..7d931ad4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,76 @@ -# Conventions for pushing code to `snmachine` +# Contributing to `snmachine` -## Import Conventions +The goal of this guide is to help users contribute to `snmachine` as quickly and as easily possible. -Conventions from Pep8 (https://pep8.org/). +# Table of contents +1. [Creating an Issue](#issues) +2. [Submitting a Pull Request](#prs) +3. [Code Style](#style) +4. [Running Tests Locally](#testing) +5. [Package Versioning](#version) + + +## Creating an Issue + +To report bugs, request features, or ask questions about the structure of the +code, please [open an issue](https://github.com/LSSTDESC/snmachine/issues) + +### Bugs + +For program crash, or to report a specific error, please file an issue by +opening a [Bug Report](https://github.com/LSSTDESC/snmachine/issues/new?assignees=&labels=bug&template=BUG.md&title=%5BBUG%5D) + +Follow instructions contained in the Github issue template in order to provide +enough detail that the `snmachine` developers can tackle the problem. + +### Feature Requests + +For feature requests or enhancement suggestions, please file a [Feature Request issue](https://github.com/LSSTDESC/snmachine/issues/new?assignees=&labels=feature&template=feature_request.md&title=%5BFEATURE%5D) + +A detailed explanation of what idea is being proposed should be put in the body +of the issue. The title can be appended with `[RFC]` to signify a "Request for +Comments" is desired on how best to incorporate said feature or to discuss at +length `[RFD]` may be used instead as a marker for "Request for Discussion" + +### General + +If the issue is general, perhaps just a question, or minor fix required, a plain +issue would be appropriate. These can be opened with a [normal issue](https://github.com/LSSTDESC/snmachine/issues/new) + + +## Submitting a Pull Request + +We welcome [pull requests](https://help.github.com/articles/about-pull-requests/) from anyone +interested in contributing to `snmachine`. This section describes best practices +for submitting PRs to this project. + +If you are interested in making changes that impact the way `snmachine` works, +please [open an issue](#issues) proposing what you would like to work on before +you spend time creating a PR. + +To submit a PR, please follow these steps: + +0. [Create an issue](#issues) and make note of the issue number +1. Fork `snmachine` to your GitHub account +2. Create a branch from `dev` on your fork with the convention of: `issue//one-or-two-word-token-description-of-issue` + - If you are working on a `[FEATURE]`, please branch from `dev` with the + convention of: `feauture//one-or-two-word-token-description-of-issue`, this is to allow for issues to be raised on specific features also, which would then have the convention of: + `feature//issue//short-description`(where issues on a particular feautre would be branched from the feature-branch in question) + +3. Make changes, add code etc and open a PR + +Please ensure your branch is up-to-date with `dev` branch by rebasing your changes. If unsure how to approach this, make a comment in the PR that has been opened. + + +## Code Style + +Much of our code style follows the convention defined in [PEP8](https://pep8.org/). + +In addition, codebase guidelines outlined in the [LSST Developer Guide](https://developer.lsst.io/python/style.html) +and in the [LSST DESC Coding Guidelines](https://confluence.slac.stanford.edu/display/LSSTDESC/Interim+LSST+DESC+Paper+Tracking?preview=/217813295/244908471/LSST%20DESC%20Coding%20Guidelines%20v1.1.pdf) +document + +#### Import Conventions Imports should be grouped in the following order: @@ -12,7 +80,7 @@ Imports should be grouped in the following order: There should be a blank line between each group of imports. -## Naming Conventions +### Naming Conventions * class names -> PascalCase * function and variable names -> snake_case @@ -20,9 +88,9 @@ There should be a blank line between each group of imports. * hidden function names -> same as function names but starting with `_` * descriptive names that minimize the number of necessary comments -## Documentation Conventions +### Documentation Conventions -### Functions +#### Functions They should follow NumPy Style (https://numpydoc.readthedocs.io/en/latest/format.html). @@ -98,3 +166,47 @@ def foo(var1, var2, long_var_name='hi'): pass ``` + + +## Running Tests Locally + +We use Azure Pipelines to automatically run tests and other +automated checks on every PR commit and merge to `master` and `dev` branches. + +However, if you would like to run the test suite locally, one can simply run: +```i{bash} +cd /path/to/snmachine/ && pytest -vs tests/ +``` + +## Package Versioning + +### Version Format + +We follow semantic versioning for `snmachine` releases, `MAJOR`.`MINOR`.`PATCH`: + +* the `MAJOR` version will be updated when incompatible API changes are made, +* the `MINOR` version will be updated when functionality is added in a +backwards-compatible manner, and +* the `PATCH` version will be updated when backwards-compatible bug +fixes are made. + +For more details, see https://semver.org/ + +Furthermore, `snmachine` adopts the release formatting of +[PEP440](https://www.python.org/dev/peps/pep-0440/) + +### Release Planning + +The authors of this package have adopted [milestones on github](https://help.github.com/en/articles/about-milestones) as a vehile to +scope and schedule upcoming releases. The main goal for a release is written in +the milestone description. Then, any ideas, specific functionality, bugs, etcs +submitted as [issues](https://help.github.com/en/articles/about-issues) +pertinent to that goal are tagged for that milestone. Goals for milestone are +discussed openly via a github issue. + +Past and upcoming releases can be seen on the [snmachine milestones +page](https://github.com/LSSTDESC/snmachine/milestones). + +For details on how the API has altered across versions, please refer to the +[`CHANGELOG.md`](https://www.github.com/LSSTDESC/snmachine/CHANGELOG.md) file, +which documents changes made and where breaking changes would have been introduced. From 85af28c8c74d11348fb0f5a0ca4fe3084257f657 Mon Sep 17 00:00:00 2001 From: Tarek Allam Date: Mon, 13 May 2019 17:19:35 +0100 Subject: [PATCH 4/6] Updating PR template Moving instructions for how to update the contributors repo with snmachine into a hidden comment, as opposed to being inline with the check mark. Since it is outlined in CONTRIBUTING.md that one should fork snmachine and then make changes in their local repo, it is expected that they should update the dev branch from "upstream" --- .github/PULL_REQUEST_TEMPLATE.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 920225eb..e6940552 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,5 +1,5 @@ **IMPORTANT: Please create an issue first before opening a Pull Request.** -Linked to issue(s): _put link_ +Linked to issue(s): _put link here_ ## Type of change @@ -23,4 +23,12 @@ How is the issue this PR is referenced against solved with this PR? - [ ] My code follows the style guidelines of this project - [ ] I have made corresponding changes to the documentation - [ ] I have added tests that prove my fix is effective or that my feature works -- [ ] I am up to date with `dev` branch via `git rebase dev` at the time of this PR +- [ ] I am up to date with `dev` branch of `snmachine` at the time of this PR + From bc86a776a4c1f6e640816299aa300bdef5b8a27f Mon Sep 17 00:00:00 2001 From: Tarek Allam Date: Mon, 13 May 2019 17:23:55 +0100 Subject: [PATCH 5/6] Fixing typo in syntax highlighting render --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7d931ad4..a8a6e74d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -174,7 +174,7 @@ We use Azure Pipelines to automatically run tests and other automated checks on every PR commit and merge to `master` and `dev` branches. However, if you would like to run the test suite locally, one can simply run: -```i{bash} +```{bash} cd /path/to/snmachine/ && pytest -vs tests/ ``` From fde186aed49de5586179d40bed7b744bd0b36635 Mon Sep 17 00:00:00 2001 From: Tarek Allam Date: Mon, 13 May 2019 17:29:03 +0100 Subject: [PATCH 6/6] Minor comment on PEP8 E501 exception As well as fixing typo and upper-casing github --> Github --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- CONTRIBUTING.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e6940552..ed565b3e 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -30,5 +30,5 @@ this can be achieve with `git pull --rebase upstream dev` If this reveals a myriad of conflicts, one can run: `git rebase --abort` and then one can submit a PR without checking the above box. -If you would like assistance with this, people contact on of the core developers +If you would like assistance with this, people contact one of the core developers of snmachine for help--> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a8a6e74d..4e1cf6e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,7 +55,7 @@ To submit a PR, please follow these steps: 2. Create a branch from `dev` on your fork with the convention of: `issue//one-or-two-word-token-description-of-issue` - If you are working on a `[FEATURE]`, please branch from `dev` with the convention of: `feauture//one-or-two-word-token-description-of-issue`, this is to allow for issues to be raised on specific features also, which would then have the convention of: - `feature//issue//short-description`(where issues on a particular feautre would be branched from the feature-branch in question) + `feature//issue//short-description`(where issues on a particular feature would be branched from the feature-branch in question) 3. Make changes, add code etc and open a PR @@ -64,7 +64,7 @@ Please ensure your branch is up-to-date with `dev` branch by rebasing your chang ## Code Style -Much of our code style follows the convention defined in [PEP8](https://pep8.org/). +Much of our code style follows the convention defined in [PEP8](https://pep8.org/), with the exception in some cases of [`E501`](https://lintlyci.github.io/Flake8Rules/rules/E501.html) In addition, codebase guidelines outlined in the [LSST Developer Guide](https://developer.lsst.io/python/style.html) and in the [LSST DESC Coding Guidelines](https://confluence.slac.stanford.edu/display/LSSTDESC/Interim+LSST+DESC+Paper+Tracking?preview=/217813295/244908471/LSST%20DESC%20Coding%20Guidelines%20v1.1.pdf) @@ -197,12 +197,12 @@ Furthermore, `snmachine` adopts the release formatting of ### Release Planning -The authors of this package have adopted [milestones on github](https://help.github.com/en/articles/about-milestones) as a vehile to +The authors of this package have adopted [milestones on Github](https://help.github.com/en/articles/about-milestones) as a vehile to scope and schedule upcoming releases. The main goal for a release is written in the milestone description. Then, any ideas, specific functionality, bugs, etcs submitted as [issues](https://help.github.com/en/articles/about-issues) pertinent to that goal are tagged for that milestone. Goals for milestone are -discussed openly via a github issue. +discussed openly via a Github issue. Past and upcoming releases can be seen on the [snmachine milestones page](https://github.com/LSSTDESC/snmachine/milestones).