Contributing to the AllenSDK

February 17, 2026 ยท View on GitHub

Project status and contribution scope (maintenance mode)

AllenSDK is in selective maintenance mode.

What this means for contributors:

  • Pull requests for bug fixes, security fixes, documentation improvements, tests, and targeted compatibility fixes are actively welcome.
  • Community contributions are welcome, including feature PRs.
  • Maintainers are not planning to develop new features.
  • Compatibility updates are best-effort and may be declined if they require major refactoring, ecosystem migrations, or substantial ongoing maintenance.
  • Some issues/PRs may be closed as not planned based on maintainer capacity and project scope.

Before starting large changes, please open an issue to discuss scope and maintenance impact.

Contributing

Thank you for your interest in contributing! There are a few ways you can contribute to the AllenSDK project:

How contributions are prioritized

Changes most likely to be accepted:

  1. Small and low-risk
  2. Backward compatible
  3. Well-tested
  4. Low long-term maintenance cost

Changes that may be declined:

  • Major rewrites or architectural changes
  • Supporting additional platforms/toolchains not currently supported
  • Ongoing maintenance commitments beyond current maintainer capacity

Answering User Questions

A great way to contribute to the AllenSDK is to help answer user questions on the forums or StackOverflow. Assisting new users is not only a valuable service for the community, but also contributes to a wider culture of scientific collaboration.

Bug Reports and Feature Requests

Before reporting a bug or requesting a feature, use Github's issue search to see if anyone else has already done so. Don't reopen an issue tagged with wontfix without getting consensus from maintainers in the comment thread.

Reporting Bugs

If there is no existing issue, create a new one. You should include:

  • A brief, descriptive title
  • A clear description of the problem
  • If you are reporting a bug, your description should contain the following information:
    • What you did (preferably the actual code or commands that you ran)
    • What happened
    • What you were expecting to happen
    • How your system is configured (operating system, Python version)

If you are comfortable addressing this issue yourself, take a look at the guide to contributing code below.

Possible triage outcomes include: accepted, needs-info, help wanted, or not planned. An issue may be closed as not planned when the implementation cost or maintenance burden exceeds current project scope/capacity.

Add Example Notebooks

Adding example notebooks are a great way to contribute to documentation and help other users get started on the AllenSDK. Take a look at our existing notebooks as a general guide for the style and content. We have many great notebooks, but Extracellular Electrophysiology Data is a good one to take a look at to get a sense for what we're looking for. All new notebook contributions should be compatible with Python 3.10+.

Notebook Guidelines:

  • Provide notebooks for major features/interfaces.
  • Use markdown cells for titles, explanatory text, and subtitles that clarify your code.
  • Include external references additional resources as needed.
  • Import your libraries in the first code cell.
  • Display your graphics inline -- for example, using the magic command %matplotlib inline.
  • Try to keep the cells of your notebook fairly simple. Think of a cell as a paragraph in a book; its contents should support a single idea.
  • Make sure all of the cells are required and in order -- you should be able to execute all cells in the notebook from the top down.
  • Check in your cell outputs. We do not currently build notebooks when we generate documentation due to the long runtime for some examples.
  • Save your notebook in doc_template/examples_root/examples/nb.

Suggesting Features/Enhancements

Before suggesting a feature or enhancement, please check existing issues first.

Because AllenSDK is in selective maintenance mode, maintainers are unlikely to implement new features directly. Community feature PRs are welcome, but acceptance depends on long-term maintenance cost and scope fit.

When suggesting a feature, please include:

  • Clear motivation and use case
  • Expected user impact
  • API/design sketch (if applicable)
  • Testing plan

When proposing or contributing a new feature, consider:

  • Is the change clearly explained and motivated?
  • Would the enhancement be useful for a broad set of users?
  • Can it be implemented with low long-term maintenance burden?
  • Does it preserve backward compatibility?
  • Could it be better maintained as a third-party extension/project?

Asking Questions

  • Is your question about the Allen Software Development Kit, or about Allen Institute data and tools more generally?
  • If you do have an AllenSDK question, first check the documentation (including the examples and the api reference) to make sure that your question is not already addressed.
    • If you can't find an answer in the documentation, please create an issue on Github.

Contributing Code

If you are able to improve the AllenSDK, send us your pull requests! Contributing code yourself can be a great way to include the features you want in the AllenSDK.

To contribute code, please follow this list:

Deciding What to Contribute

GitHub issues are used for planning and triage. In maintenance mode, filtering for good first issue, help wanted, bug, and documentation/testing tasks is a good way to find issues that are a good fit for outside contributions.

Setting Up

Code contributions should be submitted in the form of a pull request. Here are the steps:

  • Make sure that there is an issue tracking your work. See above for guidelines on creating effective issues.

  • Create a fork of the AllenSDK and clone it to your development environment.

  • Make a new branch for your code off of master. We suggest the following convention for branch naming: <type>/<short-description>. For example:

    fix/auto-reward-key
feat/parallel-behavior-analysis
docs/update-contributing-guide

  • Create an environment and install with test dependencies: pip install -e ".[test]"

  • Start writing code!

Style Guidelines

We follow PEP-8 guidelines for new python code. We also follow PEP-484 for type annotations. Before submitting a pull request, run flake8 and mypy linters to check the style of your code. All new code contributions should be compatible with Python 3.10+.

Docstrings

Docstrings for new code should follow the Numpy docstring standard. This allows us to ensure consistency in our auto-generated API documentation.

Testing Guidelines

All code you write should have unit tests, including bugfixes (since the presence of bugs likely indicates a gap in test coverage). We use pytest for running unit tests.

If you write a new file foo.py, you should place its unit tests in test_foo.py. Follow the directory structure of the parent module(s) for your tests so that they are easy to find. For example, tests for allensdk/brain_observatory/foo.py should be in allensdk/test/brain_observatory/test_foo.py.

Testing Guidelines

  • Smaller, faster tests are better (and more likely to be run!)
  • Tests should be deterministic
  • Tests should be hermetic. They should be packed with everything they need and start any fake services they might need.
  • Tests should work every time; use dependency injection to mock out flaky or long-running services.

Committing Guidelines

We use Conventional Commits for commit messages.

The format is:

<type>: <short summary>

Optional longer description.

Common types: fix, feat, docs, test, refactor, ci, chore.

Examples:

fix: correct pixel resolution fallback for zero values

feat: add parallel behavior analysis support

docs: update contribution guidelines for maintenance mode

If a commit relates to a GitHub issue, reference it in the summary or body:

fix: correct pixel resolution fallback (#1234)

Keep commits granular and readable. Group small related changes into a single commit when it makes sense. Your commits should tell a clear story.

Making a Pull Request

  • Make sure your tests pass locally first (make test or python -m pytest <a test file or directory>)
  • Update your forked repository and rebase your branch onto the latest master branch.
  • Target the master branch for your PR.
  • Use a brief but descriptive title, preferably in conventional commit format.
  • Include a short description of your changes in the body of the pull request.
  • Support your changes with additional resources. Having an example notebook or visualizations can be very helpful during the review process.

Review Process

Once your pull request has been made and your tests are passing, a maintainer will review it. Please be patient, as review timing may vary. Once approved, a maintainer will merge your changes into master. Releases are made periodically based on maintainer availability and priority fixes.

If in doubt how to do anything, don't hesitate to ask!