Thanks for taking the time to make Neet better! 🎉 😄
Note: These contributing guidelines are adapted from the Atom Project's Contributing Guidelines.
This project, and everyone participating in it, is governed by the Neet Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to emergence@asu.edu.
This section guides you through submitting a bug report for Neet. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
Before creating bug reports, perform a cursory search to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one. If you find a closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
Bugs are tracked as GitHub issues. After you are sure the bug is either new, or needs to be readdressed, create an issue and provide the following information by filling in the template.
Explain the problem and include addition details to help maintainers reproduce the problem:
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as many details as possible. For example, include a minimal script to reproduce the bug.
- Describe the behavior you observed from the script and point out exactly what the problem is with that behavior. For example, include any output you observe and explain what is wrong with it.
- Explain what behavior you expected to see instead and why.
Provide more context by answering these questions:
- Did the problem start happening recently (e.g. after updating to a new version of Neet) or was this always a problem?
- If this problem started recently, can you reproduce the problem in an older version of Neet? What is the most recent version of Neet which does not have this bug?
- Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it typically occurs.
- If the problem is related to working with external resources (e.g. data files, network connections, etc...), does the problem happen for all resources, or only some? For example, is there a particular data file that seems to cause problems, or are all data file an issue?
Include details about your configuration
- Which version of Neet are you using?
- What's the name and version of the Operating System you are using?
This section guides you through submitting an feature suggestion for Neet, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion, find related suggestions, and prioritize feature development.
Before creating a feature request, perform a cursory search to see if it has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
Feature requests are tracked GitHub issues. After you are sure the request is not a duplicate, create an issue and provide the following information by filling in the template.
- Use a clear and descriptive title for the issue to identify the suggestion.
- Provide a description of the feature in as much detail as possible.
- Propose an API for the feature to demonstrate how that feature fits in with the rest of Neet.
- Give and example usage for the proposed API. Of course, the output is not necessary.
- Reference any resources on which the feature is based. The references should any mathematical details necessary for implementing the feature, e.g. defining equations.
Your contributions are more than welcome! It's also advisable that you read through the API documentation to make sure that you fully understand how the various components of Neet interact before you get started.
For external contributions, we use GitHub forks and pull requests workflow. To get started with contributing code, you first need to fork Neet to one of your accounts. As you begin development, have several recommendations that will make your life easier.
- Do not work directly on master. Create a branch for whatever feature or bug you are currently working on.
- Create a draft pull request after you first push to your fork. This will ensure that the rest of the Neet community knows that you are working on a given feature or bug.
- Fetch changes from ELIFE-ASU/Neet's master branch often and merge them into your working branch. This will reduce the number and severity of merge conflicts that you will have to deal with. How do I fetch changes from ELIFE-ASU/Neet?
The Fork-Pull Request process described here has several goals:
- Maintain Neet's quality
- Quickly fix problems with Neet that are important to users
- Engage the community in working to make Neet as near to perfect as possible
- Enable a sustainable system for Neet's maintainers to review contributions
Please follow these steps to have your contribution considered by the maintainers:
- Use a clear and descriptive title for your pull request.
- Follow all instructions in the pull request template.
- Follow the styleguides
- After you submit your pull request, verify that all
status checks are passing.
What if the status checks are failing?
If a status check is failing, it is your responsibility to fix any problems. Of course the maintainers are here to help, so please post a comment on the pull request if you need any support from us. If you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe that to be the case. A maintainer will re-run the status checks for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our own status check suite.
- Use the present tense ("Add c-sensitivity" not "Added c-sensitivity")
- Use the imperative mood ("Add fix_canalizing parameter..." not "Adds fix_canalizing parameter...")
- Limit the first line to 72 characters or less
- Reference issues and pull requests liberally after the first line
- When only changing documentation, include
[ci skip]in the commit title - Consider starting the commit message with an applicable emoji:
- 🎨
:art:when improving the format/structure of the code - 🐎
:racehorse:when improving performance - 📝
:memo:when writing documentation - 🐧
:penguin:when fixing something on Linux - 🍎
:apple:when fixing something on maxOS - 🏁
:checkered_flag:when fixing something on Window - 🐛
:bug:when fixing a bug - 🔨
:hammer:when adding code or files - 🔥
:fire:when removing code or files - 💚
:green_heart:when fixing the CI build - ✔️
:heavy_check_mark:when adding or modifying tests - ⬆️
:arrow_up:when upgrading dependencies - ⬇️
:arrow_down:when downgrading dependencies - 👕
:shirt:when dealing with linter warnings
- 🎨
All Python code must adhere to the PEP 8 Style Guide for Python Code.
To enforce this, we use both autopep8 and flake8. We recommend running these before each commit (consider setting up a pre-commit hook). To run them manually:
$ autopep8 --in-place --recursive neet test
$ flake8 neet test- Use Sphinx
- Use reStructuredText
- Use Markdown for file unrelated to live documentation
- Each module, class, function and method should be documented using a Python docstring.
- Be very liberal with examples in documentation
- Use math whenever applicable.
All modules should have a docstring which roughly adheres to the following template::
"""
.. currentmodule:: neet.boolean.logicnetwork
.. testsetup:: logicnetwork
from neet.boolean.examples import myeloid
If the module contains more than computational unit (classes, functions, etc...) then
you should describe the relationship between the components and provide a list of them
using autosummary:
.. autosummary::
:nosignatures:
LogicNetwork
myfunc
If there are multiple classes, it is ideal to provide an inheritance diagram (if applicable):
.. inheritance-diagram:: neet.boolean.logicnetwork
:parts: 1
"""All classes should have a docstring which roughly adheres to the following template:
class LogicNetwork(BooleanNetwork):
"""
A short, one-sentence description. Follow up with as much detail as you reasonably can about the
inheritance structure and methods provided by the class. This is a good place to include an
inheritance diagram and list of methods/properties/attributes of the class:
.. inheritance-diagram:: LogicNetwork
:parts: 1
.. autosummary::
:nosignatures:
update
Move on to describe initialization. The ``__init__`` method does not need a docstring since
you'll be describing what it does here. Include examples of initialization:
.. rubric:: Examples
.. doctest:: logicnetwork
>>> LogicNetwork([((0, 1), {'00', '11'}), ((0,1), {'01','10})])
<neet.boolean.logicnetwork.LogicNetwork object at 0x...>
Also, don't be afraid to use inline :math:`E = mc^2` or block math:
.. math::
s(f, x) = \\sum_{j = 1}^N f(x) \\oplus f(x \\oplus e_j)
Finish up with the parameters and error conditions
:param table: the first argument
:type table: list, numpy.ndarray
:raises IndexError: under some condition
"""
def __init__(self, table):
pass
"""With the exception of __init__ (see (Classes)[#classes]), all functions and methods should have a
docstring which roughly adhere to the following template:
def update(self, state):
"""
A short, one-sentence description. Follow up with as many details as you can, within reason.
.. rubric:: Examples
.. doctest:: logicnetwork
>>> myeloid.update([0,0,1,0,0,1,0,0,1,0,0])
[1, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0]
:param x: a description of the first argument
:type x: list, numpy.ndarray
:return: a description of the return value and type (:class:`numpy.ndarray`)
:raises ValueError: under some condition
.. seealso:: :meth:`LogicNetwork.example_method`
"""
passUsing autodoc
All of the API documentation lives within docs/source/api. Each module gets it's own RST file, with the files layed out on disk similar to the structure in the source directory. While we are using autodoc to extract the docstrings from the python source, we don't do that automatically. Instead, we prefer to be able to specify the order of the various methods, functions, properties, etc... on the page. This means that you'll have to add a directive to the corresponding documentation source if you add a new entity to Neet. For example, the docs/source/api/boolean/network.rst is formatted as
BooleanNetwork
--------------
.. automodule:: neet.boolean.network
:synopsis: Generic Boolean Networks
.. autoclass:: neet.boolean.BooleanNetwork
.. automethod:: subspace
.. automethod:: distance
.. automethod:: hamming_neighborsIf you add a new attribute or method to
neet.boolean.network.BooleanNetwork,
you will need to add a corresponding .. autoattribute:: or .. automethod:: directive to the
above file.
After you have cloned your fork, add the ELIFE-ASU/Neet as a remote:
$ git add remote elife https://github.com/ELIFE-ASU/NeetTo fetch changes from ELIFE-ASU/Neet's master branch:
$ git fetch elife masterThis will get all of the changes from the main repository's master branch, but it will not merge any
of those changes into your local working branches. To do that, use merge:
$ git checkout master
$ git merge elife/master
...You can then merge the changes into your feature branch (say csensitivity)
$ git checkout csensitivity
$ git merge masterand then deal with any merge conflicts as usual.