forked from graspologic-org/graspologic
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Bulk License and Compliance (graspologic-org#463)
* Copyright headers and license information added to the top of every python file. LICENSE.txt added with MIT license and LICENSE file with APLv2 license removed. Note: this means we are changing the licensing from Apache License to MIT License. We have received agreement from all contributors to this change. Updated CONTRIBUTING.md file with new information, though I suspect it will break the sphinx docs page being generated now. Going to coordinate fixing that in a different way with @bdpedigo, but specifically trying to make sure we take advantage of the Github flavored markdown as much as possible. README.md still needs more work. * Update CONTRIBUTING.md Co-authored-by: Benjamin Pedigo <benjamindpedigo@gmail.com> * Update CONTRIBUTING.md Co-authored-by: Jaewon Chung <jaewonc78@gmail.com> * Adding a period, but mostly trying to trigger another build Co-authored-by: Dwayne Pryce <dwpryce@microsoft.com> Co-authored-by: Benjamin Pedigo <benjamindpedigo@gmail.com> Co-authored-by: Jaewon Chung <jaewonc78@gmail.com>
- Loading branch information
1 parent
a07feb5
commit 5d0aa9a
Showing
72 changed files
with
338 additions
and
509 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -121,3 +121,5 @@ docs/bpedigo/ase_clustering.py | |
notebooks/bpedigo | ||
|
||
*.DS_Store | ||
.idea | ||
*.iml |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,39 +1,144 @@ | ||
Contributing to GraSPy | ||
====================== | ||
# Contributing | ||
|
||
(adopted from scikit-learn) | ||
This project welcomes contributions and suggestions. Most contributions require you to | ||
agree to a Contributor License Agreement (CLA) declaring that you have the right to, | ||
and actually do, grant us the rights to use your contribution. For details, visit | ||
https://cla.microsoft.com. | ||
|
||
The latest contributing guide is available in the repository at | ||
`docs/contributing.rst`, or online at: | ||
When you submit a pull request, a CLA-bot will automatically determine whether you need | ||
to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the | ||
instructions provided by the bot. You will only need to do this once across all repositories using our CLA. | ||
|
||
https://graspy.neurodata.io/contributing.html | ||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). | ||
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) | ||
or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. | ||
|
||
There are many ways to contribute to GraSPy, with the most common ones | ||
being contribution of code or documentation to the project. Improving the | ||
documentation is no less important than improving the library itself. If you | ||
find a typo in the documentation, or have made improvements, do not hesitate to | ||
submit a GitHub pull request. Documentation can be found under the | ||
[doc/](https://github.com/neurodata/graspy/tree/master/doc) directory. | ||
# Issue Submission (Bug or Feature) | ||
|
||
But there are many other ways to help. In particular answering queries on the | ||
[issue tracker](https://github.com/neurodata/graspy/issues), and | ||
investigating bugs are very valuable contributions that decrease the burden on | ||
the project maintainers. | ||
We use GitHub issues to track all bugs and feature requests; feel free to open an issue if you have found a bug or wish | ||
to see a feature implemented. | ||
|
||
Another way to contribute is to report issues you're facing, and give a "thumbs | ||
up" on issues that others reported and that are relevant to you. It also helps | ||
us if you spread the word: reference the project from your blog and articles, | ||
link to it from your website, or simply star it in GitHub to say "I use it". | ||
In case you experience issues using this package, do not hesitate to submit a ticket to our | ||
[Issue Tracker](https://github.com/microsoft/graspologic/issues). You are also welcome to post feature requests or pull | ||
requests. | ||
|
||
Quick links | ||
----------- | ||
It is recommended to check that your issue complies with the following rules before submitting: | ||
|
||
* [Submitting a bug report or feature request](http://graspy.neurodata.io/contributing.html#submitting-a-bug-report-or-a-feature-request) | ||
* [Contributing code](http://graspy.neurodata.io/contributing.html#contributing-code) | ||
* [Coding guidelines](http://graspy.neurodata.io/contributing.html#guidelines) | ||
- Verify that your issue is not being currently addressed by other | ||
[issues](https://github.com/microsoft/graspologic/issues?q=) or | ||
[pull requests](https://github.com/microsoft/graspologic/pulls?q=). | ||
|
||
Code of Conduct | ||
--------------- | ||
- If you are submitting a bug report, we strongly encourage you to follow the guidelines in | ||
[How to create an actionable bug report](#how-to-create-an-actionable-bug-report) | ||
|
||
We abide by the principles of openness, respect, and consideration of others | ||
of the Python Software Foundation: https://www.python.org/psf/codeofconduct/. | ||
## How to create an actionable bug report | ||
|
||
When you submit an issue to [Github](https://github.com/microsoft/graspologic/issues), please do your best to | ||
follow these guidelines! This will make it a lot faster for us to respond to your issue. | ||
|
||
- The ideal bug report contains a **short reproducible code snippet**, this way | ||
anyone can try to reproduce the bug easily (see [this](https://stackoverflow.com/help/mcve) for more details). | ||
If your snippet is longer than around 50 lines, please link to a [gist](https://gist.github.com) or a github repo. | ||
|
||
- If not feasible to include a reproducible snippet, please be specific about | ||
what **estimators and/or functions are involved and the shape of the data**. | ||
|
||
- If an exception is raised, please **provide the full traceback**. | ||
|
||
- Please include your **operating system type and version number**, as well as | ||
your **Python and graspologic versions**. This information | ||
can be found by running the following code snippet:: | ||
|
||
import platform; print(platform.platform()) | ||
import sys; print(f"Python {sys.version}") | ||
import graspy; print(f"GraSPy {graspy.__version__}") | ||
|
||
- Please ensure all **code snippets and error messages are formatted in | ||
appropriate code blocks**. See | ||
[Creating and highlighting code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks) | ||
for more details. | ||
|
||
# Contributing Code | ||
|
||
## Git workflow | ||
|
||
The preferred workflow for contributing to Graspologic is to fork the main repository on GitHub, clone, and develop on a | ||
branch. Steps: | ||
|
||
1. Fork the [project repository](https://github.com/microsoft/graspologic) by clicking on the ‘Fork’ button near the top | ||
right of the page. This creates a copy of the code under your GitHub user account. For more details on how to | ||
fork a repository see [this guide](https://help.github.com/articles/fork-a-repo/). | ||
|
||
2. Clone your fork of the Graspologic repo from your GitHub account to your local disk: | ||
|
||
```bash | ||
git clone git@github.com:YourGithubAccount/graspologic.git | ||
cd graspologic | ||
``` | ||
|
||
3. Create a feature branch to hold your development changes: | ||
|
||
```bash | ||
git checkout -b my-feature | ||
``` | ||
|
||
Always use a `feature` branch. Pull requests directly to either `dev` or `main` will be rejected | ||
until you create a feature branch based on `dev`. | ||
|
||
4. Develop the feature on your feature branch. Add changed files using `git add` and then `git commit` files: | ||
|
||
```bash | ||
git add modified_files | ||
git commit | ||
``` | ||
|
||
After making all local changes, you will want to push your changes to your fork: | ||
```bash | ||
git push -u origin my-feature | ||
``` | ||
|
||
## Pull Request Checklist | ||
|
||
We recommended that your contribution complies with the following rules before you submit a pull request: | ||
|
||
- Follow the [coding-guidelines](guidelines). | ||
- Give your pull request a helpful title that summarizes what your contribution does. | ||
- Link your pull request to the issue (see: | ||
[closing keywords](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue) | ||
for an easy way of linking your issue) | ||
- All public methods should have informative docstrings with sample usage presented as doctests when appropriate. | ||
- At least one paragraph of narrative documentation with links to references in the literature (with PDF links when | ||
possible) and the example. | ||
- If your feature is complex enough that a doctest is insufficient to fully showcase the utility, consider creating a | ||
Jupyter notebook to illustrate use instead | ||
- All functions and classes must have unit tests. These should include, at the very least, type checking and ensuring | ||
correct computation/outputs. | ||
- All functions and classes should be rigorously typed with Python 3.5+ | ||
[`typehinting`](https://docs.python.org/3/library/typing.html). Validate your typehinting by running `mypy ./graspy` | ||
- All code should be automatically formatted by `black`. You can run this formatter by calling: | ||
```bash | ||
pip install black | ||
black path/to/your_module.py | ||
``` | ||
- Ensure all tests are passing locally using `pytest`. Install the necessary | ||
packages by: | ||
|
||
```bash | ||
pip install pytest pytest-cov | ||
pytest | ||
``` | ||
|
||
# Guidelines | ||
|
||
## Coding Guidelines | ||
|
||
Uniformly formatted code makes it easier to share code ownership. Graspologic package closely follows the official | ||
Python guidelines detailed in [PEP8](https://www.python.org/dev/peps/pep-0008/) that detail how code should be | ||
formatted and indented. Please read it and follow it. | ||
|
||
## Docstring Guidelines | ||
|
||
Properly formatted docstrings is required for documentation generation by Sphinx. The graspologic package closely | ||
follows the numpydoc guidelines. Please read and follow the | ||
[numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html#overview) guidelines. Refer to the | ||
[example.py](https://numpydoc.readthedocs.io/en/latest/example.html#example) provided by numpydoc. |
Oops, something went wrong.