Skip to content
This repository has been archived by the owner on Sep 27, 2024. It is now read-only.

Latest commit

 

History

History
218 lines (154 loc) · 8.26 KB

CONTRIBUTING.md

File metadata and controls

218 lines (154 loc) · 8.26 KB
Raw

Contribute to Model Card Toolkit

Model Card Toolkit can only grow through the contributions of this community. Thanks so much for your enthusiasm and your work—we appreciate everything you do!

There are many ways to contribute to Model Card Toolkit! You can contribute code, improve tests and API documentation, or create new end-to-end examples. Code contributions are not the only way to help the community. Proposing usability and design improvements, answering questions, and helping others are also immensely valuable.

It also helps us if you spread the word! Reference the library in blog posts about the awesome projects it made possible, shout out on social media every time it has helped you, or simply star the repository to say thank you.

For more ways to contribute, refer to GitHub's guide to making open source contributions

However you choose to contribute, please follow Google's Open Source Community Guidelines.

This guide was heavily inspired by other guides in the Tensorflow GitHub organization and the 🤗 Transformers guide to contributing.

Contributing Code

If you have improvements to Model Card Toolkit, send us your pull requests! Before writing any code, we strongly advise you to search through the existing pull requests or issues to make sure nobody is already working on the same thing.

If you would like to contribute code and are not sure where to start, take look at issues with the labels "good first issue" or "contributions welcome".

When you find an issue that you want to work on, please leave a comment so other people know you're working on it. If you need help or would prefer to work on the issue with others, you may use the issue comment thread ask questions or coordinate.

Code reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. For those just getting started, GitHub has a pull requests guide.

Before submitting your pull request for review, make sure your changes follow the Model Card Toolkit guidelines and coding style. Maintainers and other contributors will review your pull request. Please participate in the discussion and make the requested changes.

Contributor License Agreements

We'd love to accept your patches! Before we can take them, we have to jump a couple of legal hurdles.

Please fill out either the individual or corporate Contributor License Agreement (CLA).

  • If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an individual CLA.
  • If you work for a company that wants to allow you to contribute your work, then you'll need to sign a corporate CLA.

Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it. Once we receive it, we'll be able to accept your pull requests.

NOTE: Only original source code from you and other people that have signed the CLA can be accepted into the main repository.

Setting up a local development environment

Follow these steps to install model-card-toolkit:

  1. Install Bazel, which powers the protobuf stub code generation. Confirm that Bazel is installed and executable:

    bazel --version

  2. Fork the repository by clicking on the Fork button on the repository's page. This creates a copy of the code under your GitHub user account.

  3. Clone your fork to your local machine:

    git clone git@github.com:<your GitHub username>/model-card-toolkit.git
cd model-card-toolkit

  4. Create and activate a virtual environment:

    python3 -m venv env
source env/bin/activate
pip install --upgrade pip

  5. Install the model-card-toolkit[all] development package in editable mode:

    pip install -e ".[all]"

    If you only plan to make changes to parts of the codebase that don't require optional dependencies, you may install model-card-toolkit[test] instead.

    pip install -e ".[test]"

    When you install the library in editable mode (with the -e flag), your local changes will be picked up without needing to re-install the library.

Re-generating protobuf stub code

If you make changes to a .proto file, you should re-generate the protobuf stub code before using it. The command used to do this is automatically invoked once when you first install model-card-toolkit in editable mode, but further stub generation requires manual invocation.

bazel run //proto_build:move_generated_files

Licenses

Include a license at the top of new files.

Bazel BUILD files also need to include a license section. See BUILD example.

Do not include a license at the top of Jinja template files.

Python coding style

Changes to Model Card Toolkit Python code should conform to the Google Python Style Guide with indentation width of 2 spaces.

Linting your code

Please check your code for linting errors before submitting your pull request for review. Pull requests are lint checked using pre-commit and pylint. If you want to run the pre-commit checks locally, run following command from your local project directory:

pre-commit run --all-files

Testing your changes

Writing and updating unit tests

Include unit tests when you contribute new features, as they help to a) prove that your code works correctly, and b) guard against future breaking changes to lower maintenance costs. Bug fixes also generally require creating or updating unit tests, because the presence of bugs usually indicates insufficient test coverage.

In general, all Python files have at least one corresponding test file. For example, awesome.py should have a corresponding awesome_test.py.

If a test suite requires an optional dependency, check conftest.py to verify if it can be automatically ignored with --ignore-requires-optional-deps based on its file pattern. If it can't be automatically ignored, either update the list of patterns to ignore in conftest.py or mark the tests to be skipped if the dependency is not installed.

Running unit tests

To run a specific test suite, e.g. ModelCardTest, run its test file:

pytest model_card_toolkit/model_card_test.py

To run all tests, run:

pytest model_card_toolkit

Use the following command to skip tests that require optional dependencies:

pytest model_card_toolkit --ignore-requires-optional-deps

Use the following command to fail skipped tests:

pytest model_card_toolkit --fail-if-skipped

In general, tests are marked as skip if they require optional dependencies that aren't installed. Failing skipped tests let us catch when tests are skipped even though all optional dependencies are installed.

Being a Code Owner

Code owners are automatically requested for review when someone opens a pull request that modifies code that they own. Code ownership is tracked through the CODEOWNERS file.

You may request to become a code owner if you have made substantial contributions to the project such as guiding project meetings, contributing a major feature, or maintaining code.