Add code of conduct and contributing guides

.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# Install the pre-commit hooks below with
+# 'pre-commit install'
+
+# Auto-update the version of the hooks with
+# 'pre-commit autoupdate'
+
+# Run the hooks on all files with
+# 'pre-commit run --all'
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.4.0
+  hooks:
+  - id: end-of-file-fixer
+    # only include python files
+    files: \.py$
+  - id: debug-statements
+    # only include python files
+    files: \.py$
+  - id: trailing-whitespace
+    # only include python files
+    files: \.py$
+
+- repo: https://github.com/pycqa/flake8
+  rev: '6.1.0'
+  hooks:
+  - id: flake8

CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at brainpy@foxmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

docs/advanced_tutorials.rst

@@ -35,3 +35,13 @@ Advanced dynamics analysis
    :maxdepth: 1
 
    tutorial_advanced/advanced_lowdim_analysis.ipynb
+
+
+Developer guides
+---------------
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorial_advanced/contributing.md
+

docs/tutorial_advanced/contributing.md

@@ -0,0 +1,173 @@
+# Contributing to BrainPy
+
+Everyone can contribute to BrainPy, and we value everyone's contributions. There are several
+ways to contribute, including:
+
+- Improving or expanding BrainPy's [documentation](http://brainpy.readthedocs.io/)
+- Contributing to BrainPy's [code-base](https://github.com/brainpy/BrainPy)
+- Contributing to BrainPy's [examples](https://brainpy-examples.readthedocs.io/)
+- Contributing in any of the above ways to the broader ecosystem of libraries built on BrainPy. 
+
+## Ways to contribute
+
+We welcome pull requests, in particular for those issues marked with
+[help wanted](https://github.com/brainpy/BrainPy/labels/help%20wanted) or
+[good first issue](https://github.com/brainpy/BrainPy/labels/good%20first%20issue).
+
+For other proposals, we ask that you first open a GitHub
+[Issue](https://github.com/brainpy/BrainPy/issues) 
+to seek feedback on your planned contribution.
+
+## Contributing code using pull requests
+
+We do all of our development using git, so basic knowledge is assumed.
+
+Follow these steps to contribute code:
+
+1. Fork the BrainPy repository by clicking the **Fork** button on the
+   [repository page](http://www.github.com/brainpy/BrainPy). This creates
+   a copy of the BrainPy repository in your own account.
+
+2. Install Python >= 3.9 locally in order to run tests.
+
+3. `pip` installing your fork from source. This allows you to modify the code
+   and immediately test it out:
+
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/BrainPy
+   cd BrainPy
+   pip install -r requirements-dev.txt  # Installs all testing requirements.
+   pip install -e .  # Installs BrainPy from the current directory in editable mode.
+   ```
+
+4. Add the BrainPy repo as an upstream remote, so you can use it to sync your
+   changes.
+
+   ```bash
+   git remote add upstream https://www.github.com/brainpy/BrainPy
+   ```
+
+5. Create a branch where you will develop from:
+
+   ```bash
+   git checkout -b name-of-change
+   ```
+
+   And implement your changes using your favorite editor (we recommend
+   [Visual Studio Code](https://code.visualstudio.com/) or 
+   [PyCharm](https://www.jetbrains.com/pycharm/)).
+
+6. Make sure your code passes BrainPy's lint and type checks, by running the following from
+   the top of the repository:
+
+   ```bash
+   pip install pre-commit
+   pre-commit run --all
+   ```
+
+   See {ref}`linting-and-type-checking` for more details.
+
+7. Make sure the tests pass by running the following command from the top of
+   the repository:
+
+   ```bash
+   pytest -n auto tests/
+   ```
+
+   BrainPy's test suite is quite large, so if you know the specific test file that covers your
+   changes, you can limit the tests to that; for example:
+
+   ```bash
+   pytest -n auto brainpy/_src/tests/test_mixin.py
+   ```
+
+   You can narrow the tests further by using the `pytest -k` flag to match particular test
+   names:
+
+   ```bash
+   pytest -n auto brainpy/_src/tests/test_mixin.py -k testLogSumExp
+   ```
+
+   BrainPy also offers more fine-grained control over which particular tests are run;
+   see {ref}`running-tests` for more information.
+
+8. Once you are satisfied with your change, create a commit as follows (
+   [how to write a commit message](https://chris.beams.io/posts/git-commit/)):
+
+   ```bash
+   git add file1.py file2.py ...
+   git commit -m "Your commit message"
+   ```
+
+   Then sync your code with the main repo:
+
+   ```bash
+   git fetch upstream
+   git rebase upstream/main
+   ```
+
+   Finally, push your commit on your development branch and create a remote
+   branch in your fork that you can use to create a pull request from:
+
+   ```bash
+   git push --set-upstream origin name-of-change
+   ```
+
+   Please ensure your contribution is a single commit (see {ref}`single-change-commits`)
+
+9. Create a pull request from the BrainPy repository and send it for review.
+    Check the {ref}`pr-checklist` for considerations when preparing your PR, and
+    consult [GitHub Help](https://help.github.com/articles/about-pull-requests/)
+    if you need more information on using pull requests.
+
+(pr-checklist)=
+
+## BrainPy pull request checklist
+
+As you prepare a BrainPy pull request, here are a few things to keep in mind:
+
+(single-change-commits)=
+
+### Single-change commits and pull requests
+
+A git commit ought to be a self-contained, single change with a descriptive
+message. This helps with review and with identifying or reverting changes if
+issues are uncovered later on.
+
+**Pull requests typically comprise a single git commit.** (In some cases, for
+instance for large refactors or internal rewrites, they may contain several.)
+In preparing a pull request for review, you may need to squash together
+multiple commits. We ask that you do this prior to sending the PR for review if
+possible. The `git rebase -i` command might be useful to this end.
+
+(linting-and-type-checking)=
+
+### Linting and Type-checking
+
+BrainPy uses [mypy](https://mypy.readthedocs.io/) and [flake8](https://flake8.pycqa.org/)
+to statically test code quality; the easiest way to run these checks locally is via
+the [pre-commit](https://pre-commit.com/) framework:
+
+```bash
+pip install pre-commit
+pre-commit run --all
+```
+
+If your pull request touches documentation notebooks, this will also run some checks
+on those (See {ref}`update-notebooks` for more details).
+
+### Full GitHub test suite
+
+Your PR will automatically be run through a full test suite on GitHub CI, which
+covers a range of Python versions, dependency versions, and configuration options.
+It's normal for these tests to turn up failures that you didn't catch locally; to
+fix the issues you can push new commits to your branch.
+
+### Restricted test suite
+
+Once your PR has been reviewed, a BrainPy maintainer will mark it as `Pull Ready`. This
+will trigger a larger set of tests, including tests on GPU and TPU backends that are
+not available via standard GitHub CI. Detailed results of these tests are not publicly
+viewable, but the BrainPy maintainer assigned to your PR will communicate with you regarding
+any failures these might uncover; it's not uncommon, for example, that numerical tests
+need different tolerances on TPU than on CPU.