Guide to contributing code to Specify

Documentation Technical Docs
1

Thank you for the interest in contributing to Specify’s codebase! We welcome contributions of all kinds, including bug fixes, improvements, documentation, etc.

We value contributions from all members of the community, regardless of experience level. Whether you are a seasoned open source contributor or a newcomer to the world of software development, your help is greatly appreciated.

To get started with contributing to Specify 7, this guide will provide you with the information you need to understand the project, its goals, and how you can help.

We also encourage you to reach out to the Specify 7 team with any questions you may have. You can contact the team at support@specifysoftware.org.

Code Review and Integration Philosophy

Our contribution process is grounded in clear requirements, thoughtful changes, and collaborative review. Before contributing, please review our SCC Mission Statement and Core Values.

  1. We expect all new features to be preceded by strong requirements that have been reviewed and approved by our team. If you are interested in contributing to the main codebase, please share requirements with us in advance so we can provide feedback, or propose features based on requirements written by the core SCC team.

  2. Make commits as atomic and descriptive as possible. We want to understand the thought process behind code contributions. We encourage the use of Conventional Commits to make commit history easier for both people and tooling to read.

  3. Submit work as pull requests in this repository. If you are interested in contributing a pull request, contact support@specifysoftware.org with your GitHub username.

When opening a pull request, follow the PR template and include:

  • A clear description of the PR
  • Screenshots for relevant UI changes
  • Testing instructions (what you tested and how to validate it)

Getting Started

Preferred way to do Specify 7 development is though our development composition.

Documentation for getting development Docker composition working

Issue Tracking

All feature requests and bugs are tracked on GitHub. Each issue is sorted into a project. Each project represents a major Specify 7 component.
A list of all projects

If you found a bug, feel free to open a GitHub issue. Similarly, if you are interested in fixing some issue or adding new feature, feel free to do so! If you want to work on a larger feature, it would be best if you get in touch with us first so that we can make sure the process is smooth and efficient.

First Steps

It’s recomended to start with issues that are labled with good first issue as those require less knowledge of the codebase and are as not urgent. These would prepare you for taking on larger GitHub issues.

Code Documentation

Review The Architecture

Front-End

On the front-end, we are using TypeScript, React and Tailwind CSS.

Back-End

Back-end uses Python and Django. It also works closely with a MySQL/MariaDB database both though Django ORM and though SQLAlchemy.

IDE Setup

No special IDE configuration is required, but some optional plugins would improve developer experience. That document includes a short list.

For a full list, see GitHub - specifysystems/code-principles: A central place for code-style guidelines and best practices for Specify and Lifemapper organizations · GitHub

In the browser, you can install React Devtools extension to make debugging React components easier.

Code-Style

We prefer functional programming paradigm. In our opinion, perfect code* consist of small and pure functions that have clear unit tests, and can be combined together to solve a complex task.

On a static analysis side, we use strict TypeScript type checking and Prettier formatting to make code less buggy and more consistent.

Additionally, ESLint goes beyond that to provide close to a thousand of static analysis checks and quick fixes, all in a name of clear and bug-free code. Our ESLint configuration is located in @maxxxxxdlp/eslint-config-react

Support

A great deal of user-facing documentation is available in the Speciforum. Most of it is available to users from member institutions only, thus consider joining the Specify Software Consortium if you are interested in becoming a user of Specify 7.

If you are stuck and need help, consider emailing our support at support@specifysoftware.org, opening a GitHub issue or posting a question on our Discourse forum as appropriate.

Contact Option Link
General Inquiry support@specifysoftware.org
Bug Report GitHub Issue
User Question Discourse Forum

Installing Specify Locally

If you just want to get Specify 7 running, the process is simple: clone the repository, make sure Docker is available, and run docker compose up from the project root. The application will initialize itself and guide you through setup in the browser.

What You Need

Install the following on your machine:

  • Docker Desktop with the Docker Compose plugin.
  • Git for cloning the repository.
  • VS Code or another editor you are comfortable with.
  • A MariaDB/MySQL client if you want command-line access to the database.
  • Optional: a database GUI such as DBeaver CE.

If you want the command-line client on macOS, install it without a server:

brew install mysql-client
echo 'export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

On Ubuntu/Debian:

sudo apt-get update && sudo apt-get install -y mariadb-client

[!warning]
Do not install a local MariaDB/MySQL server. Specify 7 runs its database inside Docker.

Quick Start

  1. Clone the repository.

    git clone https://github.com/specify/specify7.git
cd specify7

  2. Start the application.

    docker compose up

  3. Open the app in your browser at http://localhost/specify.

  4. Follow the guided setup process to finish initializing Specify 7.

That is the default path. No separate demo database download is required.

Optional: Start With Existing Data

If you want to begin with data already loaded, place a seed database file in the seed-database/ directory before running docker compose up.

You can use:

The seed database is upgraded automatically to the latest Specify 7 version during setup, regardless of the version it started from.

Optional: Python Virtual Environment

The app itself runs in Docker, but a Python virtual environment is still useful for helper scripts.

python3 -m venv ve
source ve/bin/activate
pip3 install wheel
pip3 install --upgrade -r requirements.txt

On Windows PowerShell:

.\ve\Scripts\Activate.ps1

Troubleshooting

If setup does not start cleanly, reset the Docker environment and try again:

docker compose down -v --remove-orphans
docker compose up

If you are using a seed database, confirm the file is still in seed-database/ before restarting.

Specify 7 Installation Instructions