Contributors Guidelines#

Hi! Thank you for taking the time to contribute to DISDRODB.

You can contribute in many ways:

Join the GitHub discussions
Report software issues
Help us develop new readers
Add new data to the DISDRODB Decentralized Data Archive
Implement new products
…
Any code improvements are welcome!

We develop with GitHub!

We use GitHub to host code, to track issues and feature requests, as well as accept Pull Requests. We use GitHub flow. So all code changes happen through Pull Requests (PRs).

First-Time Contributors?

Before contributing, please take a moment to read through the following sections:

The Installation for contributors section helps you set up the development environment and pre-commit hooks.
The Contributing process section provides a brief overview of the steps each DISDRODB developer must follow to contribute to the repository.
The Code review checklist section enables faster code review.
The Code of conduct details the expected behavior of all contributors.

Initiating a discussion about your ideas or proposed implementations is a vital step before starting your contribution! Engaging with the community early on can provide valuable insights, ensure alignment with the project’s goals, and prevent potential overlap with existing work. Here are some guidelines to facilitate this process:

Start with a conversation

Before you start coding, open a GitHub Discussion, a GitHub Feature Request Issue, or start a discussion in the DISDRODB Slack Workspace. These communication channels provide an opportunity to gather feedback, understand the project’s current state, and improve your contributions.
Seek guidance and suggestions

Utilize the community’s expertise. Experienced contributors and maintainers can offer guidance, suggest best practices, and help you navigate any complexities you might encounter.
Collaborate on the approach

Discussing your implementation strategy allows for a collaborative approach to problem-solving. It ensures that your contribution is in line with the project’s design principles and technical direction.

By following these steps, you not only enhance the quality and relevance of your contribution but also become an integral part of the project’s collaborative ecosystem.

If you have any questions, please ask in the GitHub Discussions or DISDRODB Slack Workspace.

Issue Reporting Guidelines#

To facilitate and enhance the issue reporting process, it is important to use the predefined GitHub Issue Templates. These templates ensure you provide all essential information in your report, enabling a faster and more effective response from the maintainers. You can access these templates at the GitHub Issue Templates page.

However, if the existing templates don’t match your specific issue, please suggest a new template. Your feedback is invaluable for refining our processes and addressing a broader spectrum of concerns. To do this, create a general issue in the repository, clearly state that you’re requesting a new template, and include detailed suggestions about what it should entail. This proactive approach helps us continuously evolve and better serve the needs of the project and its contributors.

Contributing process#

Here is a brief overview of the steps each DISDRODB developer must follow to contribute to the repository:

Fork the repository.
Create a new branch for each contribution.
Work on your changes.
Test your changes.
Push your local changes to your fork repository.
Create a new Pull Request in GitHub.

https://github.com/ltelab/disdrodb/blob/main/docs/source/static/collaborative_process.png?raw=true

1. Fork the repository and install the development environment#

If you do not have a GitHub account yet, please create one here. If you do not have Git installed on your computer, please install it following these instructions. Then, follow the guidelines in the Installation for contributors section to create a local copy of the disdrodb repository, set up the development environment, and install the pre-commit hooks.

Once you have a local copy of the disdrodb repository on your machine, you’re ready to contribute!

2. Create a new branch#

Each contribution should be made in a separate new branch of your forked repository. For example, if you plan to contribute new readers, create a branch for each individual reader. Working directly on the main branch is reserved for Core Contributors only. Core Contributors are developers who actively maintain the repository. They are the only ones who accept Pull Requests and push commits directly to the DISDRODB repository.

For more information on how to create and work with branches, see “Branches in a Nutshell” in the Git documentation.

Please define the name of your branch based on the scope of the contribution. Strictly follow these guidelines:

If you add a reader: reader-<data_source*>-<campaign>
If you fix a bug: bugfix-<some_key>-<word>
If you improve the documentation: doc-<some_key>-<word>
If you add a new feature: feature-<some_key>-<word>
If you refactor code: refactor-<some_key>-<word>
If you optimize code: optimize-<some_key>-<word>

* Guidelines for the <data_source>:

Use the institution name when campaign data spans more than 1 country (e.g., ARM, NASA)
Use the country name when all campaigns (or sensor networks) are within a given country

3. Work on your changes#

When working on your changes, please adhere to the repository’s coding style and documentation rules.

Code Style

We follow the PEP 8 style guide for python code. Another relevant style guide can be found in the The Hitchhiker’s Guide to Python.

To ensure minimal style consistency, we use black to auto-format the source code. The black configuration used in DISDRODB is defined in the pyproject.toml.

Code Documentation

Every module, function, or class must have a docstring describing its purpose and how to use it. The docstrings follow the conventions described in PEP 257 and the Numpy’s docstrings format.

Here is a summary of the most important rules:

Always use triple quotes for docstrings, even if they fit on a single line.
For one-line docstring, end the phrase with a period.
Use imperative mood for all docstrings (“””Return some value.”””) rather than descriptive mood (“””Returns some value.”””).

Here is an example of a docstring:

def adjust_lag2_corrcoef1(gamma_1, gamma_2):
   """
   A simple adjustment of lag-2 temporal autocorrelation coefficient to
   ensure that the resulting AR(2) process is stationary when the parameters
   are estimated from the Yule-Walker equations.

   Parameters
   ----------
   gamma_1 : float
     Lag-1 temporal autocorrelation coefficient.
   gamma_2 : float
     Lag-2 temporal autocorrelation coefficient.

   Returns
   -------
   out : float
     The adjusted lag-2 correlation coefficient.
   """

If you are using VS Code, you can install the autoDocstring extension to automatically create such preformatted docstrings.

You should configure VS Code as follows:

The convention we adopt for our docstrings is the NumPy docstring convention.

4. Code quality control#

Pre-commit hooks are automated scripts that run during each commit to detect basic code quality issues. If a hook identifies an issue (signified by the pre-commit script exiting with a non-zero status), it halts the commit process and displays the error messages.

Currently, DISDRODB tests that the code to be committed complies with black’s format style, the ruff linter, and the codespell spelling checker.

Tool	Aim	pre-commit	CI/CD
Black	Python code formatter	👍	👍
Ruff	Python linter	👍	👍
Codespell	Spelling checker	👍	👍

The versions of the software used in the pre-commit hooks are specified in the .pre-commit-config.yaml file. This file serves as a configuration guide, ensuring that the hooks are executed with the correct versions of each tool, thereby maintaining consistency and reliability in code quality checks.

If a commit is blocked due to these checks, you can manually correct the issues by running the appropriate tool locally: black . for Black, ruff check . for Ruff, or codespell for Codespell. Alternatively, use the pre-commit run --all-files command to attempt automatic corrections of all formatting errors across all files.

The Continuous Integration (CI) tools integrated within GitHub employ the same pre-commit hooks to consistently uphold code quality for every Pull Request.

In addition to the pre-commit hooks, the Continuous Integration (CI) setup on GitHub incorporates an extended suite of tools. These tools, which are not installable on a local setup, perform advanced code quality analyses and reviews after each update to a Pull Request.

Refer to the table below for a comprehensive summary of all CI tools employed to assess the code quality of a Pull Request.

Tool	Aim
pre-commit.ci	Run pre-commit (as defined in .pre-commit-config.yaml )
CodeScene	Automated code review and analysis tools
CodeFactor	Automated code review and analysis tools
Codacy	Automated code review and analysis tools

5. Code testing with pytest#

DISDRODB tests are written using the third-party pytest package. Every code change must be tested!

The tests are organized within the /disdrodb/tests directory and are structured to comprehensively assess various aspects of the code.

These tests are integral to the development process and automatically run on GitHub upon new commits or Pull Request updates. The Continuous Integration (CI) on GitHub runs tests and analyzes code coverage using multiple Python versions, multiple operating systems, and multiple versions of dependency libraries to ensure the code works in various environments.

The following tools are used:

Tool	Aim
Pytest	Execute unit tests and functional tests
Coverage	Measure the code coverage of the project’s unit tests
CodeCov	Uses Coverage to track and analyze code coverage over time.
Coveralls	Uses Coverage to track and analyze code coverage over time.

For contributors interested in running the tests locally:

Ensure you have the development environment correctly set up.
Navigate to the disdrodb root directory.
Execute the following command to run the entire test suite:

pytest

For more focused testing or during specific feature development, you may run subsets of tests. This can be done by specifying either a sub-directory or a particular test module.

Run tests in a specific sub-directory:

pytest disdrodb/tests/<test_subdirectory>/

Run a particular test module:

pytest disdrodb/tests/<test_subdirectory>/test_<module_name>.py

These options provide flexibility, allowing you to efficiently target and validate specific components of the disdrodb software.

Note

Each test module must be prefixed with test_ to be recognized and selected by pytest. This naming pattern is a standard convention in pytest and helps in the automatic discovery of test files.

6. Push your changes to your fork repository#

During this process, pre-commit hooks will be run. Your commit will be allowed only if quality requirements are fulfilled.

If you encounter errors, you can attempt to fix the formatting errors with the following command:

pre-commit run --all-files

7. Create a new Pull Request in GitHub.#

Once your code has been uploaded into your DISDRODB fork, you can create a Pull Request (PR) to the DISDRODB main branch.

Recommendation for the Pull Requests:

Please fill it out accurately the Pull Request template.
It is perfectly fine to make many small commits as you work on a Pull Request. GitHub will automatically squash all the commits before merging the Pull Request.
If adding a new feature:
- Provide a convincing reason to add the new feature. Ideally, propose your idea through a Feature Request Issue and obtain approval before starting work on it. Alternatively, you can present your ideas in the GitHub Discussions or in the DISDRODB Slack Workspace.
- Implement unit tests to verify the functionality of the new feature. This ensures that your addition works as intended and maintains the quality of the codebase.
If fixing bug:
- Provide a comprehensive description of the bug within your Pull Request. This aids reviewers in understanding the issue and the impact of your fix.
- If your Pull Request addresses a specific issue, add (fix #xxxx) in your PR title to link the PR to the issue and enhance the clarity of release logs. For example, the title of a PR fixing issue #3899 would be <your PR title> (fix #3899).
- If applicable, ensure that your fix includes appropriate tests. Adding tests for your bug fix helps prevent future regressions and maintains the stability of the software.

Code review checklist#

Once your Pull Request is ready, ask the maintainers to review your code.
When you complete the changes suggested by reviewers, do another self-review of the code and write a comment to notify the reviewer that the Pull Request is ready for another iteration.
Resolve all review comments, ensuring they are all addressed before the next review iteration.
If you are not going to follow a code review recommendation, please add a comment explaining why you think the reviewer’s suggestion is not relevant.
Avoid writing comments like “done” or “fixed” on each code review comment. Reviewers assume you will make all suggested changes unless you have a reason not to implement some of them.

Credits#

Thank you to all the people who have already contributed to DISDRODB repository!

If you have contributed data and/or code to disdrodb, add your name to the AUTHORS.md file.

Contributors Guidelines

Contents

Contributors Guidelines#

Issue Reporting Guidelines#

Contributing process#

1. Fork the repository and install the development environment#

2. Create a new branch#

3. Work on your changes#

4. Code quality control#

5. Code testing with pytest#

6. Push your changes to your fork repository#

7. Create a new Pull Request in GitHub.#

Code review checklist#

Credits#