Skip to content

Latest commit

 

History

History
133 lines (89 loc) · 5.45 KB

CONTRIBUTING.md

File metadata and controls

133 lines (89 loc) · 5.45 KB
Raw

Contributing to Cryostat

Welcome to Cryostat 👋! First off, thanks for taking the time to contribute!

All types of contributions are encouraged and valued. See the Table of Contents for different ways to contribute. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉

Table of Contents

I Have a Question

Before you ask a question, it is best to search for existing Issues that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first.

If you then still feel the need to ask a question and need clarification, we recommend the following:

  • Open an Issue.
  • Provide as much context as you can about what you're running into.
  • Provide project and platform versions (mvn, podman, etc), depending on what seems relevant.
  • Add a question label to your issue for easy search.

We will then take care of the issue as soon as possible.

I Want To Contribute

Report Issues

We use GitHub issues to track bugs and errors. If you run into an issue with the project:

  • Open an Issue.
  • Explain the behavior you would expect and the actual behavior.
  • Please provide as much context as possible and describe the reproduction steps that someone else can follow to recreate the issue on their own. This usually includes your code.

Good report tips

A good report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. If you are looking for support, you might want to check this section.

Workflow

This is a simple guide of the workflow being used in Cryostat. We will use https://github.com/cryostatio/cryostat as an example.

Set up SSH with Github

See https://docs.github.com/en/authentication/connecting-to-github-with-ssh. If you prefer to use https, you can skip this step.

Fork the upstream repository

See https://docs.github.com/en/get-started/quickstart/fork-a-repo

Local changes

Clone the forked repository.

$ git clone [email protected]:<username>/cryostat.git
$ git remote add upstream [email protected]:cryostatio/cryostat.git # Adding upstream as remote

Navigate to cryostat directory and checkout a new branch.

$ cd cryostat && git checkout -b some-task-branch

Edit some files and commits your changes.

$ git add . # Stage your changes. Here, we stage the entire repo (recursively).
$ git commit -m "<type>(<scope>): a nice description of your work"

Open a PR

Push your changes to your remote respository (forked). You might need to rebase on the latest commit on the upstream's main.

To rebase:

$ git fetch upstream # Fetch upstream commits
$ git rebase upstream/main # Rebase on latest commit on upstream/main

To push:

$ git push -u origin some-task-branch # First time push
# or
$ git push -f origin some-task-branch # If already pushed to origin remote

Visit upstream repository and open a PR.

visit-upstream

Compare changes across forks (your branch in fork to the upstream main).

select-compare-across-forks

Add:

  • A title following guidelines.
  • A description with a referenced issue that the PR is for.
  • A label (depending on your PR scope).
  • A list of reviewers (at least one approval is required).

Note: You might not be able to add reviewers and labels. Don't worry! The project team will add them accordingly.

prepare-pull-requests

Once its done, you can click Create Pull Request and wait for approval.

pull-requests-approved

Some useful PR commands

Once a PR is created you can:

  • comment /request_review to request review from the cryostatio/reviewers team. This will add a label review-requested which will be removed if changes are requested.

Result

Your changes will be squashed into a single commit on main with the message including your PR title, and branch commit messages. From there, you can safely delete your branch.

To delete:

$ git checkout main # Must checkout a different branch before deleting the current checked out one
$ git branch -D some-task-branch # Delete local branch with force or without force using -d
$ git push --delete origin some-task-branch # Delete branch on origin (forked)

Now, you can rebase your local and origin main with latest upstream:

$ git fetch upstream
$ git checkout main
$ git rebase upstream/main
$ git push origin main # Update origin remote