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..ed565b3e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,34 @@ +**IMPORTANT: Please create an issue first before opening a Pull Request.** +Linked to issue(s): _put link here_ + +## 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 of `snmachine` at the time of this PR + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..4e1cf6e5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,212 @@ +# Contributing to `snmachine` + +The goal of this guide is to help users contribute to `snmachine` as quickly and as easily possible. + +# 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 feature 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/), 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) +document + +#### Import Conventions + +Imports should be grouped in the following order: + +1. standard library imports (https://docs.python.org/3/library/) +2. related third party imports (like `numpy`, `pandas` or `snmachine`) +3. local application/library specific imports + +There should be a blank line between each group of imports. + +### Naming Conventions + +* class names -> PascalCase +* function and variable names -> snake_case +* function names -> start with descriptive verb (eg. get, compute, fit, load) +* hidden function names -> same as function names but starting with `_` +* descriptive names that minimize the number of necessary comments + +### Documentation Conventions + +#### Functions + +They should follow NumPy Style (https://numpydoc.readthedocs.io/en/latest/format.html). + +See a complete example in https://docs.scipy.org/doc/numpy-1.15.0/docs/howto_document.html#docstring-standard . +Note that not all sections are mandatory. See a short example edited from the above page: + +``` +def foo(var1, var2, long_var_name='hi'): + """A one-line summary that does not use variable names or the + function name. + + Several sentences providing an extended description. Refer to + variables using back-ticks, e.g. `var`. + + Parameters + ---------- + var1 : array_like + Array_like means all those objects -- lists, nested lists, etc. -- + that can be converted to an array. We can also refer to + variables like `var1`. + var2 : int + The type above can either refer to an actual Python type + (e.g. ``int``), or describe the type of the variable in more + detail, e.g. ``(N,) ndarray`` or ``array_like``. + long_var_name : {'hi', 'ho'}, optional + Choices in brackets, default first when optional. + + Returns + ------- + type + Explanation of anonymous return value of type ``type``. + describe : type + Explanation of return value named `describe`. + + Raises + ------ + BadException + Because you shouldn't have done that. + + Notes + ----- + Notes about the implementation algorithm (if needed). + + You may include some math: + + .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n} + + And even use a greek symbol like :math:`omega` inline. + + References + ---------- + Cite the relevant literature, e.g. [1]_. You may also cite these + references in the notes section above. + + .. [1] O. McNoleg, "The integration of GIS, remote sensing, + expert systems and adaptive co-kriging for environmental habitat + modelling of the Highland Haggis using object-oriented, fuzzy-logic + and neural-network techniques," Computers & Geosciences, vol. 22, + pp. 585-588, 1996. + + Examples + -------- + These are written in doctest format, and should illustrate how to + use the function. + + >>> a = [1, 2, 3] + >>> print [x + 3 for x in a] + [4, 5, 6] + >>> print "a\n\nb" + a + b + """ + + 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: +```{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. diff --git a/docs/contributing/conventions_for_pushes.md b/docs/contributing/conventions_for_pushes.md deleted file mode 100644 index 09510103..00000000 --- a/docs/contributing/conventions_for_pushes.md +++ /dev/null @@ -1,100 +0,0 @@ -# Conventions for pushing code to `snmachine` - -## Import Conventions - -Conventions from Pep8 (https://pep8.org/). - -Imports should be grouped in the following order: - -1. standard library imports (https://docs.python.org/3/library/) -2. related third party imports (like `numpy`, `pandas` or `snmachine`) -3. local application/library specific imports - -There should be a blank line between each group of imports. - -## Naming Conventions - -* class names -> PascalCase -* function and variable names -> snake_case -* function names -> start with descriptive verb (eg. get, compute, fit, load) -* hidden function names -> same as function names but starting with `_` -* descriptive names that minimize the number of necessary comments - -## Documentation Conventions - -### Functions - -They should follow NumPy Style (https://numpydoc.readthedocs.io/en/latest/format.html). - -See a complete example in https://docs.scipy.org/doc/numpy-1.15.0/docs/howto_document.html#docstring-standard . -Note that not all sections are mandatory. See a short example edited from the above page: - -``` -def foo(var1, var2, long_var_name='hi'): - """A one-line summary that does not use variable names or the - function name. - - Several sentences providing an extended description. Refer to - variables using back-ticks, e.g. `var`. - - Parameters - ---------- - var1 : array_like - Array_like means all those objects -- lists, nested lists, etc. -- - that can be converted to an array. We can also refer to - variables like `var1`. - var2 : int - The type above can either refer to an actual Python type - (e.g. ``int``), or describe the type of the variable in more - detail, e.g. ``(N,) ndarray`` or ``array_like``. - long_var_name : {'hi', 'ho'}, optional - Choices in brackets, default first when optional. - - Returns - ------- - type - Explanation of anonymous return value of type ``type``. - describe : type - Explanation of return value named `describe`. - - Raises - ------ - BadException - Because you shouldn't have done that. - - Notes - ----- - Notes about the implementation algorithm (if needed). - - You may include some math: - - .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n} - - And even use a greek symbol like :math:`omega` inline. - - References - ---------- - Cite the relevant literature, e.g. [1]_. You may also cite these - references in the notes section above. - - .. [1] O. McNoleg, "The integration of GIS, remote sensing, - expert systems and adaptive co-kriging for environmental habitat - modelling of the Highland Haggis using object-oriented, fuzzy-logic - and neural-network techniques," Computers & Geosciences, vol. 22, - pp. 585-588, 1996. - - Examples - -------- - These are written in doctest format, and should illustrate how to - use the function. - - >>> a = [1, 2, 3] - >>> print [x + 3 for x in a] - [4, 5, 6] - >>> print "a\n\nb" - a - b - """ - - pass -```