|
1 | | -# Contributing to FOOOF |
| 1 | +# Contributing Guidelines |
2 | 2 |
|
3 | | -Thank you for your interest in contributing to FOOOF! |
| 3 | +Thank you for your interest in contributing to `fooof`! |
4 | 4 |
|
5 | | -This documents is a set of guidelines for contributing to FOOOF on GitHub. This guide is meant to make it easy for you to get involved. Before contributing, please take a moment to read over this page to get a sense of the scope of the toolbox, and the preferred procedures for requesting features, reporting issues, and making contributions. |
| 5 | +We welcome all contributions to the project that extend or improve code and/or documentation! |
6 | 6 |
|
7 | | -* [Participation guidelines](#participation-guidelines) |
8 | | -* [How to report bugs](#how-to-report-bugs) |
9 | | -* [How to suggest changes or updates](#how-to-suggest-changes-or-updates) |
10 | | -* [How to submit code](#how-to-submit-code) |
11 | | -* [Style guidelines](#style-guidelines) |
| 7 | +This page includes information for how to get involved and contribute to the project, and guidelines for how to do so. |
12 | 8 |
|
13 | | -## Participation guidelines |
| 9 | +This project adheres to a |
| 10 | +[code of conduct](https://github.com/fooof-tools/fooof/blob/master/CODE_OF_CONDUCT.md) |
| 11 | +that you are expected to uphold when participating in this project. |
14 | 12 |
|
15 | | -Please note that this project adheres to a [code of conduct](https://github.com/fooof-tools/fooof/blob/master/CODE_OF_CONDUCT.md), that you are expected to uphold when participating in this project. |
| 13 | +On this page, you can find information on: |
16 | 14 |
|
17 | | -## How to report bugs |
| 15 | +* [Reporting a problem](#reporting-a-problem) |
| 16 | +* [Getting involved in the project](#getting-involved) |
| 17 | +* [Project scope](#project-scope) |
| 18 | +* [Making a contribution](#making-a-contribution) |
| 19 | +* [Project conventions](#project-conventions) |
18 | 20 |
|
19 | | -If you are reporting a bug, please submit it to our [issue tracker](https://github.com/fooof-tools/fooof/issues). Please do your best to include the following: |
| 21 | +## Reporting a Problem |
20 | 22 |
|
21 | | -1. A short, top-level summary of the bug (usually 1-2 sentences) |
22 | | -2. A short, self-contained code snippet to reproduce the bug, ideally allowing a simple copy and paste to reproduce. Please do your best to reduce the code snippet to the minimum required. |
| 23 | +To report an issue with the code, please submit it to our [issue tracker](https://github.com/fooof-tools/fooof/issues). |
| 24 | + |
| 25 | +In doing so, please try to include the following: |
| 26 | + |
| 27 | +1. A short, top-level summary of the issue (usually 1-2 sentences) |
| 28 | +2. A short, self-contained code snippet to reproduce the issue, ideally allowing a simple copy and paste to reproduce |
| 29 | + - Please do your best to reduce the code snippet to the minimum required |
23 | 30 | 3. The actual outcome of the code snippet |
24 | 31 | 4. The expected outcome of the code snippet |
25 | 32 |
|
26 | | -## How to suggest changes or updates |
| 33 | +## Getting Involved |
27 | 34 |
|
28 | | -If there is a feature you would like to see, please submit it as an [issue](https://github.com/fooof-tools/fooof/issues), with a brief description of what you would like to see added / changed, and why. If it is feature that you would be willing to implement, please indicate that and, and follow the guidelines below for making a contribution. |
| 35 | +We welcome all kinds of contributions to the project, including suggested features and help with documentation, maintenance, and updates. |
29 | 36 |
|
30 | | -Note that, in terms of scope, FOOOF is quite specifically focused on it's core functionality of parameterizing neural power spectra, and helper utilities to visualize and work with model results, as well as tools to create synthetic power spectra. Procedures and utilities that do not deal with operating upon power spectra or FOOOF outputs directly will most likely be considered out of scope, and won't be added into FOOOF. |
| 37 | +If you have a new idea you would like to suggest or contribute, please do the following: |
31 | 38 |
|
32 | | -## How to submit code |
| 39 | +1. Check if the idea is already being discussed on the |
| 40 | + [issues](https://github.com/fooof-tools/fooof/issues) or |
| 41 | + [development](https://github.com/fooof-tools/Development) page |
| 42 | +2. Check that your idea is within the [project scope](#project-scope) |
| 43 | +3. Open an [issue](https://github.com/fooof-tools/fooof/issues) describing |
| 44 | + what you would like to see added / changed, and why |
| 45 | +4. Indicate in the issue if the idea is something you would be willing to help implement |
| 46 | + - if so, project maintainers can give feedback to help make a plan for the contribution |
| 47 | +5. If you want to work on the contribution, follow the [contribution guidelines](#making-a-contribution) to do so |
33 | 48 |
|
34 | | -If there is a feature you would like to add, or an issue you saw that you think you can help with, you are ready to make a code submission to the project! |
| 49 | +If you are interested in getting involved and helping with the project, a great place to start is to visit the |
| 50 | +[issues](https://github.com/fooof-tools/fooof/issues) or |
| 51 | +[development](https://github.com/fooof-tools/Development) page |
| 52 | +and see if there is anything you would be interested in helping with. If so, join the conversation, and project developers can help get you started. |
35 | 53 |
|
36 | | -If you are working on a feature, please indicate so in the relevant issue, so that we can keep track of who is working on what. |
| 54 | +## Project Scope |
37 | 55 |
|
38 | | -Once you're ready to start working on your contribution, do the following: |
| 56 | +All contributions must be within the scope of the module. |
39 | 57 |
|
40 | | -1. **[Fork](https://help.github.com/articles/fork-a-repo/) this repository**. This makes your own version of this project you can edit and use. |
41 | | -2. **[Make your changes](https://guides.github.com/activities/forking/#making-changes)**, adding code that add the desired functionality. |
42 | | -3. Check through the code to make sure it follows the projects **[style guidelines](#style-guidelines)** |
43 | | -4. **Submit a [pull request](https://help.github.com/articles/proposing-changes-to-a-project-with-pull-requests/)**. |
| 58 | +`fooof` is a module for parameterizing neural power spectra. This includes model fitting, management and analysis of resulting parameters, and utilities to visualize power spectra and model results. This module also includes functionality to simulate power spectra based on the model. |
44 | 59 |
|
45 | | -If it's your first time contributing to open source, check out this free resource on [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github). |
| 60 | +Procedures and utilities that do not deal with operating upon power spectra or on model outputs will most likely be considered out of scope. Notably, this model does not include doing spectral estimation or time-domain analysis. For approaches such as these, the [neurodsp](https://github.com/neurodsp-tools/neurodsp/) module may be a more appropriate target. |
46 | 61 |
|
47 | | -## Style guidelines |
| 62 | +## Making a Contribution |
48 | 63 |
|
49 | | -All code that is to be added to FOOOF must follow the code conventions of the project. |
| 64 | +If there is a feature you would like to add, or an issue you saw that you think you can help with, you are ready to make a submission to the project! |
| 65 | + |
| 66 | +If you are working on a feature, please indicate so in the relevant issue, so that we can keep track of who is working on what. |
| 67 | + |
| 68 | +Once you're ready to start working on your contribution, do the following: |
50 | 69 |
|
51 | | -FOOOF follows the following conventions: |
52 | | -- Code style should follow [PEP8](https://www.python.org/dev/peps/pep-0008/) |
53 | | - - Merge candidate code will be checked using [pylint](https://www.pylint.org) |
54 | | - - Max line length is 100 characters |
55 | | -- All functions should be tested, using [pytest](https://docs.pytest.org/en/latest/) |
56 | | - - Merge candidates must pass all existing tests, and add new tests such as to not reduce test coverage |
57 | | -- All code should be documented, following the [numpy docs](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard) format |
58 | | -- Example sections in docstrings are recommended, if possible. |
59 | | - - If so, these examples should be executable (through doctest), or use the SKIP directive if they cannot be run |
| 70 | +1. [Fork this repository](https://help.github.com/articles/fork-a-repo/), which makes your own version of this project you can edit |
| 71 | +2. [Make your changes](https://guides.github.com/activities/forking/#making-changes), updating or adding code to add the desired functionality |
| 72 | +3. [Check the project conventions](#project-conventions), and make sure all new or updated code follows the guidelines |
| 73 | +4. [Submit a pull request](https://help.github.com/articles/proposing-changes-to-a-project-with-pull-requests/), to start the process of merging the new code to the main branch |
| 74 | + |
| 75 | +If it's your first time contributing to open source software, check out this free resource on [how to contribute to an open-source project on GitHub](https://app.egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github). |
| 76 | + |
| 77 | +## Project Conventions |
| 78 | + |
| 79 | +All code contributed to the module should follow these conventions: |
| 80 | + |
| 81 | +1. Code Requirements |
| 82 | + * All code should be written in Python, and run on the minimum required version that is noted in the README |
| 83 | + * New dependencies should be avoided if possible, especially if they are not in the Anaconda distribution |
| 84 | + * If any new dependencies are needed, they should be added to the `requirements.txt` file |
| 85 | + |
| 86 | +2. Code Style |
| 87 | + * Code should generally follow [PEP8](https://www.python.org/dev/peps/pep-0008/) style guidelines |
| 88 | + * Max line length is 100 characters |
| 89 | + * Merge candidates will be checked using [pylint](https://www.pylint.org) |
| 90 | + |
| 91 | +3. API & Naming Conventions |
| 92 | + * Try to keep the API consistent with existing code in terms of parameter names and ordering |
| 93 | + * Use standard casing, for example: |
| 94 | + * function names should be in snake_case (all lowercase with underscores) |
| 95 | + * class names should be in CamelCase (leading capitals with no separation) |
| 96 | + * If passing through arguments to an external function, the naming and ordering of parameters in this module should generally follow that of the external function |
| 97 | + |
| 98 | +4. Code Documentation |
| 99 | + * All code should be documented, including in-code comments describing procedures, and detailed docstrings |
| 100 | + * Docstrings should follow the [numpy docs](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard) format |
| 101 | + * At minimum, there should be a sentence describing what the function does and a list of parameters and returns |
| 102 | + * Private functions should be indicated with a leading underscore, and should still include a docstring including at least a sentence describing what the function does |
| 103 | + * If possible, add an `Examples` section to the docstrings, that demonstrates a simple use case |
| 104 | + * If so, these examples should be executable, using [doctest](https://docs.python.org/3/library/doctest.html) |
| 105 | + * If examples cannot be run, use the SKIP directive |
| 106 | + |
| 107 | +5. Code Tests |
| 108 | + * This project uses the [pytest](https://docs.pytest.org/en/latest/) testing tool for testing module code |
| 109 | + * All new code requires test code, written as unit tests that check each function and class in the module |
| 110 | + * Tests should be, at a minimum, 'smoke tests' that execute the code and check that it runs without raising an error |
| 111 | + * Where possible, accuracy checking is encouraged, though not strictly required |
| 112 | + * Merge candidates must pass all existing tests, and add new tests such as to not reduce test coverage |
| 113 | + * To run the tests locally, pytest needs to be installed (`pip install pytest`) |
| 114 | + * To run the tests on a local copy of the module, move into the folder and run `pytest .` |
| 115 | + |
| 116 | +6. Documentation Website |
| 117 | + * This project uses a documentation website, created using [sphinx](https://www.sphinx-doc.org/) |
| 118 | + * Any new public functions or classes should be added to the `doc/api.rst` file, so they get included in the API list |
| 119 | + * Any new functionality should be added and described in the tutorials and/or examples |
| 120 | + * If a new approach is added, a new tutorial or example may be appropriate |
| 121 | + * To build and check the documentation locally: |
| 122 | + * Install the requirements for the docsite (`pip install -r requirements-doc.txt`) |
| 123 | + * Move to the `fooof/doc` directory (`cd doc`) |
| 124 | + * Run `make html` to create a local copy of the documentation website |
| 125 | + * The documentation can then be opened in a web browser by opening the file `fooof/doc/_build/html/index.html` |
60 | 126 |
|
61 | 127 | For more guidelines on how to write well formated and organized code, check out the [Python API Checklist](http://python.apichecklist.com). |
0 commit comments