DOCSEARCHbyAlgolia
Submit Docs

Qiskit Ecosystem

repository·main·Indexed 41 days ago

https://github.com/qiskit/ecosystem

A registry and administrative hub for software, tools, and tutorials that extend the Qiskit SDK. It manages membership through a system of automated and manual 'check ups' to verify project health, compatibility with Qiskit SDK v2.0, and adherence to open-source licensing and conduct standards.

Tokens
4.6K
Snippets
12
Records
26
Agent score
51%

What's inside Qiskit Ecosystem

  1. How check up importance and cure periods work

    main

    The importance level of a check up determines its cure period, which is the grace period a project has to resolve a failure before its membership status changes.

    • Cure period: The number of days allowed for a fix.
    • none importance: The check up must pass at all times; there is no grace period.
    • no deadline (cure_period_in_days = -1): The check up shows as pending, marking the project as Under revision, but it will not automatically retire the project.

    Note: Individual check ups can override the default cure period of their importance level (marked with a :warning: in the catalog).

  2. Understand the Qiskit Ecosystem check up system

    main

    Membership in the Qiskit Ecosystem is maintained through continuous automated and manual validations called check ups. A check up is a single, named criterion (e.g., having an OSI-approved license or recent commit activity) used to verify project health.

    Each check up consists of:

    • An id: A three-character identifier (e.g., [G07], [001]) used in project pages and data.
    • Importance: Determines the cure period (the number of days a project can fail a check up before losing membership).
    • Category: Defines the type of criterion.
    • Applies to: Specifies the scope (e.g., certain check ups only apply to Python packages).

    All check ups are defined in resources/checks.toml. Automated check ups are implemented as PyTest tests in ecosystem/validation/.

  3. Update ecosystem member data

    main
    Each member of the ecosystem is stored as a TOML file in the resources/members directory. To add or update members, you should edit these TOML files. Access to these files is managed programmatically via the DAO class in ecosystem/dao.py.

  4. Change the Qiskit Ecosystem badge style

    main

    You can customize the visual appearance of your project's ecosystem badge by modifying the project's configuration file within the Qiskit Ecosystem repository.

    To change the style, submit a Pull Request to the project's .toml file located in the resources/members directory of the ecosystem repository. Update the badge.style entry to one of the supported values listed below.

    # Example change in the project's toml file
[badge]
style = "flat"

  5. How to add a new ecosystem check up

    main

    To introduce a new check up to the Qiskit Ecosystem, you must perform two steps:

    1. Define the metadata: Add a new entry to resources/checks.toml. This file serves as the single source of truth for check up ids, titles, descriptions, categories, importance levels, and cure periods.
    2. Implement the test: If the check up can be automated, implement a PyTest test within the ecosystem/validation/ directory. Ensure the checker field in your resources/checks.toml entry points to the specific test implementation.
    # Example workflow for adding a check up:
# 1. Update resources/checks.toml
# [check_up_id]
# title = "My New Check"
# checker = "path.to.test_function"

# 2. Implement the test in ecosystem/validation/test_my_check.py
# def test_my_new_check():
#     ... implementation ...

  6. Guide for project maintainers: Managing membership status

    main

    As a project member, you can monitor and manage your status via your project page and the ecosystem badge.

    Monitoring Status

    • Project Page: Check the Checkups section at https://qiskit.github.io/ecosystem/p/<short uuid>/.
    • Badge: An orange badge indicates the project is Under revision.

    Resolving Failures

    1. Fix upstream: Update your repository, release compatible packages, or add missing files (like LICENSE).
    2. Fix metadata: Correct errors in your project's TOML file by submitting a PR to the ecosystem repo or opening an update issue.
    3. Explain it: If a check up doesn't apply, request an xfailed status via an issue.
    4. Declare support expectations: If a project is no longer maintained, set the maturity to as-is or deprecated to mark it as Unmaintained and exempt it from activity check ups.

    Reversing Alumni Status

    If a project becomes Alumni, it can be reinstated by opening a pull request that removes the member.status entry from its TOML file.

  7. How to edit or remove ecosystem members

    main
    The resources/ directory contains compiled ecosystem data. To make changes to the ecosystem data (such as adding, editing, or removing a repository), do not edit the files in resources/ directly. Instead, navigate to the members/ folder and modify or delete the corresponding .toml file for that repository. Once you push these changes to the main branch, a GitHub action will automatically recompile the data and update the website.

  8. Merge a Pull Request locally

    main

    If you are managing the target repository, use these steps to merge a branch from a fork into the main branch:

    1. Switch to main: Checkout the target branch (usually main) in the target repository.
    2. Pull the feature branch: Pull the specific development branch directly from the contributor's fork repository.
    3. Merge: Merge the pulled branch into your local main branch.
    4. Push: Push the updated main branch back to the origin repository.
    # Checkout the target branch
git checkout main

# Pull the development branch from the fork
git pull https://github.com/forkuser/forkedrepo.git my-branch

# Merge the development branch
git merge newfeature

# Push the merged main branch
git push origin main

  9. Create a Pull Request for the Qiskit Ecosystem

    main

    To contribute changes to the Qiskit Ecosystem repository, follow these steps to fork, clone, and submit a Pull Request:

    1. Fork the repository: Fork https://github.com/qiskit-community/ecosystem on GitHub.
    2. Clone your fork: Clone your personal fork to your local machine.
    3. Configure upstream: Add the original repository as a remote named upstream to keep your fork synchronized.
    4. Sync with main: Checkout your local main branch and merge the changes from upstream/main.
    5. Create a feature branch: Create and switch to a new branch for your specific changes.
    6. Commit changes: Stage your changes with git add and commit them with a descriptive message.
    7. Push to GitHub: Push your new branch to your fork on GitHub.
    8. Open the PR: Navigate to your fork on GitHub in a browser and click the "compare & pull request" button. Enter your commit message and comments, then click "create new pull request".
    # Fork and Clone
git clone git@github.com:<your_user_name>/ecosystem.git

# Keep fork up-to-date
git remote add upstream https://github.com/qiskit-community/ecosystem.git
git checkout main
git merge upstream/main

# Create a new branch
git checkout main
git branch new-branch
git checkout new-branch

# Commit and Push
git add <files_you_changed>
git commit -m "message"
git push --set-upstream origin new-branch

  11. How check ups are executed and updated

    main

    Check ups are automated via GitHub Actions and follow a specific schedule:

    • Daily: The Daily | Update member data workflow refreshes metadata (GitHub activity, PyPI/Julia package info) and commits it. Fixes may take up to one day to become visible.
    • Weekly (Thursdays): The Weekly | Update member status workflow runs python manager.py members update_checkups followed by python manager.py members update_status. This opens a pull request labeled member update for human review.
    • On Submission/Member Updates: The Member validations workflow runs check ups specifically for the project being modified in a pull request.

    CLI Note: The update commands support an -e flag to exclude specific importance levels, categories, or membership statuses from the run.

  12. Run ecosystem CLI commands via manager.py

    main

    The ecosystem repository is designed to be run through GitHub Actions. The ecosystem Python package acts as a runner for CLI commands. The entrypoint is the manager.py file located in the root of the repository.

    Use the following command structure to execute functions defined in the manager file:

    python manager.py <CMD> <NAME_OF_FUNCTION_IN_MANAGER_FILE> <POSITIONAL_ARGUMENT> [FLAGS]