toolbox/CONTRIBUTING.md

![Contributing](data/gfx/CONTRIBUTING.gif)

# Contributing to Toolbox

Thank you for wanting to contribute to Toolbox! We greatly appreciate your
interest!

# Reporting Bugs

## Before Submitting a Bug Report

- Check if your issue is already reported in our [bug tracker](https://github.com/containers/toolbox/issues)
  - If the issue is already reported and is marked as **OPEN**, comment on it
    and if possible and needed, share info about the issue just as if you were
    submitting a new issue
  - If the issue is marked as **CLOSED**, check if your version of Toolbox is
    up-to-date or if there are some steps, described in the closed issue, that
    you should follow. If you are still experiencing the issue, please file a
    new issue
- See our [documentation](https://docs.fedoraproject.org/en-US/fedora-silverblue/toolbox/)
  if there are some steps that could help you solve your issue
- Sometimes a bug is not reported in our bug tracker but instead people ask for
  help somewhere else (e.g., chat channels). In such cases we'd like you to still report the bug and
  share with us any info that could be gathered from those places

## Writing a Bug Report

Writing good bug reports is a nice way to make the job of the maintainers and
other contributors a bit easier.

When writing a bug report:

- **Use a clear and descriptive title**
- **Describe the problem** - Can you reproduce the bug reliably? What first
  triggered the problem? Did it start happening after upgrading your system?
- **Provide steps how to reproduce** - It's easier for us to fix a bug if we can
  reproduce it.
- **Describe the behavior you received and what you expected** - Sometimes it
  may not be clear what the *right* behavior should look like.
- **Provide info about the version of used software** - What version of Toolbox
  and Podman do you use?
- **Provide info about your system** - What distribution do you use? Which
  desktop environment? Is it a VM or a real machine?

# Making Suggestions

Toolbox is not feature-complete and some of it's functionality is not-there-yet.
We are thankful for all suggestions and ideas but be ready that your suggestion
may be rejected.

## Before Submitting a Suggestion

- Check if your suggestion has not already been made in our [bug tracker](https://github.com/containers/toolbox/issues)
  - If it has and is marked as **OPEN**, go ahead and share your own thoughts
    about the topic!
  - If it has and is marked as **CLOSED**, please read the ticket and depending
    on whether the suggestion was accepted or not consider if it is worth
    opening a new issue or not.
- Consider if the suggestion is not too out of scope of the project.

## Writing a Suggestion

When writing a suggestion:

- **Use a clear and descriptive title**
- **Describe the idea** - What parts of Toolbox does it affect? Is it a major
  functionality or a minor tweak?
- **Provide step-by-step description of the suggested behavior** so that we
  will understand.
- **Explain why would this idea be useful** - It sounds good to have a lot of
  options but sometimes less is more. See this [article](https://ometer.com/preferences.html).

# First Contribution

Toolbox is written in [Go](https://golang.org) and uses [Meson](https://mesonbuild.com)
as it's buildsystem.

Instructions for building Toolbox from source are in our [README](https://github.com/containers/toolbox/blob/main/README.md).

> You may not need to build the project from source if your contribution is not
> related to the code of Toolbox itself (e.g., documentation, updating CI
> config, playing with image definitions,...).

Here are some ideas of what you could contribute with:

- Check our [bug tracker](https://github.com/containers/toolbox/issues)
  and look for tickets marked with labels `good-first-issue` or `help-wanted`.
- Write tests - Go has [tools](https://golang.org/pkg/testing/) for writing tests.
  There are also [some](https://github.com/stretchr/testify) [libraries](https://github.com/onsi/ginkgo)
  used for creating even more sophisticated tests.
- Play with custom images - Toolbox currently officially works with Fedora-based
  images. Ultimately there should be a wide variety of supported distro images.
  You can help with testing other people's image definitions or creating your
  own. **Beware**, maintainers still don't have a clear idea of how the image
  infrastructure should look like.
- Write documentation - Some functions in Toolbox's code don't have comments and
  it's not very clear what they do. Toolbox has it's [documentation](https://docs.fedoraproject.org/en-US/fedora-silverblue/toolbox/)
  hosted by Fedora. It's not very large and could use some attention.
- Hack on the code and share the result - Seriously! Sometimes random ideas are
  the best.

Toolbox currently does not have an infrastructure for translations. You can help
us to set it up!

# Pull Requests

All pull requests are welcome! Features, bug fixes, fixing of typos, tests,
documentation, code comments and much more.

## Creating a Pull Request

- Document well your changes - This applies to the description of your PR and to
  your commit messages.
- If possible add additional test cases - If there are no tests for the part of
  code you're contributing to, consider opening another PR if you want to
  implement it yourself or file an issue so that somebody else can pick it up.
- Update documentation to reflect your changes - Manual pages can be found in
  directory `doc`. If your changes affect Toolbox's [documentation](https://docs.fedoraproject.org/en-US/fedora-silverblue/toolbox/),
  consider creating a PR there (but to save yourself time, you can do it
  after your changes are accepted), too.
- After creating a PR add to the bottom of all your commits a link to the PR. This helps the future maintainers find discussions around the changes.

## After Creating a Pull Request

It may take the us some time to review your changes and sometimes even longer to
actually merge them. Please, don't interpret this as an act of not appreciating
your efforts! We really appreciate them! Sometimes we may be stuck in different
parts of our lives.

If it takes us a very long time to even respond to your Pull Request, you can
try to @ping us at our communication channels (see section #Communication).

## 
Toolbox has a CI (Continuous Integration) setup for running tests. Their goal is to check if your
changes don't affect adversely Toolbox's functionality. Sometimes these tests
mail fail with a false-positive. If you are not sure about the outcome of the
tests, you can try to trigger a new test run by writing a comment with text `recheck` (really just that). If the issue persists, reach out to the maintainers!

Toolbox's CI system is [Zuul](https://zuul-ci.org/) hosted at [softwarefactory](https://softwarefactory-project.io/). The CI is defined using [Ansible](https://www.ansible.com) playbooks. For more information on writing Zuul jobs see their [documentation](https://zuul-ci.org/docs/zuul/reference/user.html).

# Little Style Guide

Toolbox is written in [Go](https://golang.org) and uses its default set of tools
including `gofmt` and `golint`.

Here are some good materials to learn from about the way how to write nice and
idiomatic code in Go:

- [A Tour of Go](https://tour.golang.org/welcome)
- [How To Write Go Code](https://golang.org/doc/code.html)
- [Effective Go](https://golang.org/doc/effective_go.html)

Overall, the [Go Blog](https://blog.golang.org/) is a good place to learn more
about Go.

If you are using Visual Studio Code, there are [plugins](https://marketplace.visualstudio.com/items?itemName=golang.Go)
that include all this functionality and throw a warning if you're doing
something wrong.

# Communication

The Toolbx team hangs-out at a dedicated Matrix channel: [#toolbx:matrix.org](https://matrix.to/#/#toolbx:matrix.org).

For Fedora-specific discussions you can visit their [wiki](https://docs.fedoraproject.org/en-US/project/join/) to learn about the means to contact the community.