Contributing to Repository Service for TUF

We welcome contributions from the community and first want to thank you for taking the time to contribute!

Please familiarize yourself with the Code of Conduct before contributing.

Getting help and involved

Slack channel

#repository-service-for-tuf channel on OpenSSF Slack.

Meetings

Our community meetings happen monthly with the TUF community meetings.

RSTUF mailing list

Join the mail list https://lists.openssf.org/g/RSTUF

email: RSTUF@lists.openssf.org

Developer Certificate of Origin (DCO)

Before you start working with Repository Service for TUF, please read our Developer Certificate of Origin. All contributions to this repository must be signed as described on that page.

To acknowledge the Developer Certificate of Origin (DCO), sign your commits by appending a Signed-off-by: Your Name <example@domain.com> to each git commit message (see git commit –signoff). Your signature certifies that you wrote the patch or have the right to pass it on as an open-source patch.

Getting started

We welcome many different types of contributions and not all of them need a Pull Request. Contributions may include:

  • New features and proposals

  • Documentation

  • Bug fixes

  • Issue Triage

  • Answering questions and giving feedback

  • Helping to onboard new contributors

  • Other related activities

The Repository Service for TUF (RSTUF) has multiple components to which you can contribute: CLI, API, and Worker.

Getting the source code

Fork the repository

Choose the component you want to contribute to and follow the instructions below to get the source code.

Repository Service for TUF CLI (CLI)

Fork the repository on GitHub and clone it to your local machine:

git clone git@github.com:YOUR-USERNAME/repository-service-tuf-cli.git
cd repository-service-tuf-cli
Repository Service for TUF API (API)

Fork the repository on GitHub and clone it to your local machine:

git clone git@github.com:YOUR-USERNAME/repository-service-tuf-api.git
cd repository-service-tuf-api
Repository Service for TUF Worker (Worker)

Fork the repository on GitHub and clone it to your local machine:

git clone git@github.com:YOUR-USERNAME/repository-service-tuf-worker.git
cd repository-service-tuf-worker

Add a git remote

Add a remote and regularly sync to make sure you stay up-to-date with our repository:

Choose the component to get the instructions

Repository Service for TUF CLI (CLI)
git remote add upstream https://github.com/repository-service-tuf/repository-service-tuf-cli
git checkout main
git fetch upstream
git merge upstream/main
Repository Service for TUF API (API)
git remote add upstream https://github.com/repository-service-tuf/repository-service-tuf-api
git checkout main
git fetch upstream
git merge upstream/main
Repository Service for TUF Worker (Worker)
git remote add upstream https://github.com/repository-service-tuf/repository-service-tuf-worker
git checkout main
git fetch upstream
git merge upstream/main

Preparing the environment

Create your development environment

Verify that you have Make installed

We use Make to run, build, update docs, tests, formatting, etc. Verify that you have Make installed in your environment.

make --version

If you do not have Make installed, consult your operating system documentation on how to install make.

Docker

Why Docker?

Docker simplifies development environment set up.

RSTUF uses Docker and Docker Compose to automate setting up a “batteries included” development environment. The Dockerfile and docker-compose.yml files include all the required steps for installing and configuring all the required external services of the development environment.

Installing Docker

The best experience for building RSTUF on Windows 10 is to use the Windows Subsystem for Linux (WSL) in combination with both Docker for Windows and Docker for Linux. Follow the instructions for both platforms.

Verifying Docker installation

Check that Docker is installed: docker -v

Install Docker Compose

Install Docker Compose using the Docker-provided installation instructions.

Note

Docker Compose will be installed by Docker for Mac and Docker for Windows automatically.

Verifying Docker Compose installation

Check that Docker Compose is installed: docker compose version

Python and Pipenv

Make sure you have Python installed, we recommend the latest version of Python 3.x.

https://www.python.org/downloads/

Install Pipenv

Pipenv is a tool that automatically creates and manages a virtual environment and it is used by the RSTUF project to manage dependencies.

After installing Python, install the pipenv tool:

$ pip install pipenv

Create a virtual environment for this project:

$ pipenv shell

Install the requirements from the Pipfile.

The flag -d will install the development requirements:

$ pipenv install -d

Development

Note

RSTUF development can be done using Makefile scripts which execute all developer actions.

The Makefile contains common commands to run the development environment. You can run make help to see all the available commands.

Here are some of the most common commands:

Running the development environment

To run the development environment, use the following command:

$ make run-dev

This will start the development environment with all the required services. All changes done in the code will be reflected in the development environment.

The logs will be available in the terminal where you started the development environment.

You can stop the development environment with CTRL + C or stop it in another terminal with:

$ make stop

To clean up the development environment, use the following command:

$ make clean

Running checks with pre-commit

The pre-commit tool is installed as part of the development requirements.

To automatically run checks before you commit your changes you should run:

$ make precommit

This will install the git hook scripts for the first time, and run the pre-commit tool. Now pre-commit will run automatically on git commit.

Running tests

To run the tests, use the following command:

$ make test

How to add new dependency

Install the new package as a dependency.

If you are adding a new package that is only needed for development, use the -d flag to install it as a development dependency.

$ pipenv install -d <package>

If you are adding a new package that is needed for the application to run, use the following command without the -d flag to install it as a runtime dependency.

$ pipenv install <package>

Build local documentation

$ make docs

Reformat the code (linters)

$ make reformat

Submitting changes

  1. Create a new branch

$ git checkout -b <new_change_name>

  1. Perform the changes and commit them

$ git add <files_you_changed>
$ git commit -m "commit messaage"

  1. Push your changes to your fork

$ git push origin <your_new_branch>

  1. Run local linters, tests, etc

  2. Create a local commit with a good title and description

$ git commit -a -s

  1. Open a Pull Request

    Go to the GitHub repository and create a new Pull Request from your branch.

Check the specific repository CONTRIBUTING documentation for more specific details:

Code of Conduct