Contributor Guide

Thanks for taking time to contribute!

The following guidelines are intended to assist you in contributing to EasyGraph on GitHub. These guidelines should serve as suggestions rather than strict requirements. Please use your judgment and feel free to propose changes to this document by submitting a pull request.

Table of contents

How to contribute

How to contribute

Reporting bugs

This section guides you through submitting a bug report for EasyGraph. Adhering to these guidelines helps maintainers and the community understand your report, reproduce the behavior, and identify related reports.

Before creating bug reports, please check the following list to ensure that a new report is necessary. When you do create a bug report, please include as many details as possible and fill out the required template, as the information requested will assist maintainers in resolving the issue more quickly.

Note: If you find a Closed issue that matches the one you encountered, open a new issue and include a link to the original issue in your report.

Before submitting a bug report

How do I submit a bug report?

Bugs are tracked on the official issue tracker where you can create a new issue and provide the following information using the template.

Explain the problem and include additional details to help maintainers reproduce the problem:

  • Title: Use a descriptive and specific title that summarizes the problem.

  • Steps to Reproduce: Outline the exact steps that lead to the issue. Include specific examples, links to relevant files or GitHub projects, and code snippets.

  • Observed Behavior: Detail what happens when the steps are followed and explain why this behavior is problematic.

  • Expected Behavior: Describe what you expected to happen instead and justify why this behavior is expected.

Provide more context by answering these questions:

  • Did the issue start recently, such as after updating to a new version of EasyGraph, or has it always been a problem?

  • If the problem started happening recently, can you reproduce the problem in an older version of EasyGraph? What is the most recent version in which the problem does not occur?

  • Can you reliably reproduce the issue? If not, provide details about the frequency of the problem and the conditions under which it typically happens.

Include details about your configuration and environment:

  • Which version of EasyGraph are you using?

  • Which Python version EasyGraph has been installed for?

  • What’s the name and version of the OS you’re using?

This section guides you through submitting an enhancement suggestion for EasyGraph, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.

Before creating enhancement suggestions, please check this list as you might find out that you don’t need to create one. When you are creating an enhancement suggestion, please include as many details as possible. Fill in the template, including the steps that you imagine you would take if the feature you’re requesting existed.

Before submitting an enhancement suggestion

  • Check that your issue does not already exist in theissue tracker.

How do I submit an Enhancement suggestion?

Enhancement suggestions are tracked on the official issue tracker where you can create a new one and provide the following information:

  • Use a clear and descriptive title for the issue to identify the suggestion.

  • Provide a step-by-step description of the suggested enhancement in as many details as possible.

  • Provide specific examples to demonstrate the steps..

  • Describe the current behavior and explain which behavior you expected to see instead and why.

One of the simplest ways to get started contributing to a project is through improving documentation. EasyGraph is constantly evolving, this means that sometimes our documentation has gaps. You can help by adding missing sections, editing the existing content so it is more accessible or creating new content (tutorials, FAQs, etc).

Note: A great way to understand EasyGraph’s design and how it all fits together, is to add FAQ entries for commonly asked questions. EasyGraph members usually mark issues with candidate/faq to indicate that the issue either contains a response that explains how something works or might benefit from an entry in the FAQ.

Issues pertaining to the documentation are usually marked with the Documentation label.

Picking an issue

Note: If you are a first time contributor, and are looking for an issue to take on, you might want to look for Good First Issue labelled issues. We do our best to label such issues, however we might fall behind at times. So, ask us.

the code base, join us on our Discord Server.

Local development

To contribute to the EasyGraph codebase, you will need to set up EasyGraph locally. Refer to the official documentation to get started with EasyGraph.

Note: Local development of EasyGraph requires Python 3.8 or newer.

First, clone the repository using git and navigate to its directory:

git clone git@github.com:python-EasyGraph/EasyGraph.git
cd EasyGraph

Note: We recommend using a personal fork for this step. If you are new to GitHub collaboration, please refer to the Forking Projects Guide.

Next, install the required dependencies for EasyGraph and ensure that the current tests are passing on your machine:

pytest

EasyGraph follows the black coding style and it’s essential to ensure that your code adheres to it. Failure to comply will cause the CI to fail, and your Pull Request will not be merged.

Similarly, the import statements are sorted with isort, and it’s crucial to adhere to this style. Failure to do so will cause the CI to fail.

To prevent accidental commits of code that does not adhere to the coding style, you can install a pre-commit hook. This hook checks that everything is in order before committing:

pre-commit install

You can also execute it at any time using the following command:

pre-commit run --all-files

Your code must always be accompanied by corresponding tests. Code without accompanying tests will not be merged.

Run the Tests Locally

  • Install tox and pyenv

  • Use pyenv to install python 3.6 to 3.10, and make sure that python3.6, python3.7, …, python3.10 is in your $PATH.

  • Run tox to run the tests across python 3.6 to 3.10.

  • To run tox only on python3.9 and 3.10, use the command tox -e py39,py310.

Pull requests

  • Fill in the required template

  • Make sure that your pull request contains tests that cover the changed or added code.

  • If your changes warrant a documentation change, the pull request must also update the documentation.

Note: Make sure your branch is rebased against the latest main branch. A maintainer might ask you to ensure the branch is up-to-date prior to merging your Pull Request if changes have conflicts.

All pull requests, unless otherwise instructed, must first be accepted into the main branch (master).

If you are helping with the triage of reported issues, this section provides some useful information to assist you in your contribution.

Triage steps

  1. Attempt to reproduce the issue with the reported EasyGraph version or request further clarification from the issue author.

  2. Verify that the issue has not already been resolved. You can attempt to reproduce using the latest preview release and/or EasyGraph from the main branch.

  3. If the issue cannot be reproduced,

    1. Seek clarification from the issue’s author,

  4. If the issue can be reproduced,

    1. comment on the issue confirming so

    2. if possible, identify the root cause of the issue.

    3. Consider fixing the issue by submitting a pull request.

All development work is performed against EasyGraph’s main branch (master). All changes are expected to be submitted and accepted to this branch.

Release branch

When a release is ready, the following steps are necessary before the release is tagged.

  1. A release branch with the prefix release-, eg: release-1.1.0rc1.

  2. A pull request from the release branch to the main branch (master) if it’s a minor or major release. Otherwise, to the bug fix branch (eg: 1.0).

    1. The pull request description MUST include the change log corresponding to the release (eg: #2971).

    2. The pull request must contain a commit that updates CHANGELOG.md and bumps the project version (eg: #2971).

    3. The pull request must have the Release label specified.

  1. Tag the branch with the version identifier (eg: 1.1.0rc1).

  2. Merge the pull request once the release is created and assets are uploaded by the CI.

Note: We prefer a merge commit over a squash or rebase merge in this case.

Bug fix branch

Once a minor version (eg: 1.1.0) is released, a new branch for the minor version (eg: 1.1) is created for the bug fix releases. Changes identified or approved by the EasyGraph team as needing a bug fix should be submitted as pull requests to this branch.

The following criteria must be met for an issue to be accepted into a bug fix branch (trivial fixes may be considered on a case-by-case basis):

  1. The issue disrupts core functionality and/or is a critical regression.

  2. The change set does not introduce a new feature or change existing functionality.

  3. A new minor release is not expected within a reasonable time frame.

  4. If the issue affects the upcoming minor/major release, a corresponding fix must be accepted into the main branch.x

Note: This is subject to the interpretation of a maintainer within the context of the issue.