Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
217 lines (147 loc) · 8.73 KB

CONTRIBUTING.md

File metadata and controls

217 lines (147 loc) · 8.73 KB

Contributing Guide

Welcome to the DNF5 project! We are glad that you want to contribute!

We welcome your feedback on different areas of our project, including the following:

  • Problems found during a new developer environment setup.
  • Gaps in our documentation.
  • Bugs in automation scripts.

If you are experiencing problems with the project, let us know by opening an issue. If you want to file a bug on Fedora, you can open the bug in the Bugzilla tool.

Ways to contribute

We welcome different types of contributions, including the following:

Finding an issue

If you are a new contributor, you can search for issues with the good first issue label. These issues are suitable for contributors who are not core maintainers and want to get familiar with the codebase.

Note that sometimes there can be no issues with the good first issue label. Do not worry! There is likely still something for you to work on. If you want to contribute but you do not know where to start or cannot find a suitable issue, ask for help by reaching out to us on one of our channels.

If there is an issue that you would like to work on, add a comment saying that you want to work on this issue, for example, "I want to work on this", and assign the issue to yourself.

Asking for help

If you need any help when contributing to the project, reach out to us either of the following ways:

Submitting a contribution

Once you have a contribution ready, complete the following steps to submit the contribution:

  1. Submit a pull request (PR).
    • If the PR is not yet ready to be reviewed by the maintainers, create a "Draft Pull Request". Then, when it's ready, mark it as "Ready for review".
  2. Review the PR.
    1. Discuss the PR with one of the maintainers. Note that the maintainers might request some changes.
    2. Review the PR again.
  3. Merge the PR.

AI-assisted contributions policy

The following policy is adapted from the Fedora Council AI-Assisted Contributions Policy, which was originally authored by Jason Brooks, the Fedora Council, and the Fedora community.

You MAY use AI assistance for contributing to this project, as long as you follow the principles described below.

  1. Accountability:

    You MUST take the responsibility for your contribution.

    Contributing to this project means vouching for the quality, license compliance, and utility of your submission.

    All contributions, whether from a human author or assisted by large language models (LLMs) or other generative AI tools, must meet our standards as described in this CONTRIBUTING document.

    The contributor is always the author and is fully accountable for the entirety of these contributions.

  2. Transparency:

    You MUST disclose the use of AI tools when the significant part of the contribution is taken from a tool without changes. You MUST use an Assisted-by: <name of AI tool> line at the end of your git commit messages to do so, for example:

    • Assisted-by: generic LLM chatbot

    • Assisted-by: ChatGPTv5

    You SHOULD disclose the other uses of AI tools, where it might be useful.

    Routine use of assistive tools for correcting grammar and spelling, or for clarifying language, does not require disclosure.

  3. Contribution & Community Evaluation:

    AI tools may be used to assist human reviewers by providing analysis and suggestions.

    You MUST NOT use AI as the sole or final arbiter in making a substantive or subjective judgment on a contribution.

    The final accountability for accepting a contribution always rests with the human contributor who authorizes the action.

Setting up a development environment

To setup a development environment, complete the following steps:

  1. Install build requirements:

    dnf builddep dnf5.spec #[--define '_without_<option> 1 ...]

    NOTE: Requires Fedora of version at least 43, as the libpkgmanifest is not packaged in the lower versions, or build without the manifest plugin.

  2. Build DNF5:

    mkdir build
cd build
cmake ..
# or cmake .. [-DWITH_<OPTION>=<ON|OFF> ...]
make

  3. Run the unit-tests. To run the tests, follow the steps to build the code and then run this code:

    # from the 'build' directory
CTEST_OUTPUT_ON_FAILURE=1 make test

    Alternatively, you can execute tests in a verbose mode:

    # from the 'build' directory
make test ARGS='-V'

  4. Install DNF5. To install the built package, we recommend to build an rpm package.

    You can build the rpm package either of the following ways:

    • Build rpms by using tito:

      tito build --rpm --test

    • Build rpms from git:

      export PREFIX=$(rpmspec dnf5.spec -q --srpm --qf '%{name}-%{version}'); git archive --format=tar.gz --prefix=$PREFIX/ HEAD > $PREFIX.tar.gz
rpmbuild -ba --define "_sourcedir $(pwd)" dnf5.spec #[--with=<option>|--without=<option> ...]

License Header

New C++ and C source files should start with the following header:

// Copyright Contributors to the DNF5 project
// SPDX-License-Identifier: THE-LICENSE-IDENTIFIER

The same rule applies to other source files, with the header adjusted according to the rules of the specific language. For example, Perl, Python, and Ruby source files should start with the header:

# Copyright Contributors to the DNF5 project
# SPDX-License-Identifier: THE-LICENSE-IDENTIFIER

Replace THE-LICENSE-IDENTIFIER with either GPL-2.0-or-later or LGPL-2.1-or-later, according to COPYING.md.

Pull request checklist

When you submit your pull request or push new commits to it, our automated systems will run some checks on your new code. We require that your pull request passes these checks. However, note that there are more criteria that your pull request must pass before we can accept and merge it. We recommend that you ensure the following locally before you submit your code:

  • Code must build.

    Ensure that your code builds locally unless you need some help from us or you need us to review work in progress changes.

  • Code must be tested.

    If your pull request includes new or modified functionality within the library, we kindly request that you provide matching unit tests in the project's test directory to cover these changes. However, if the changes only affect the command-line interface, you can provide related CI tests in the ci-dnf-stack component. If you need our assistance, ask the maintainers for help.

  • Code must pass sanity checks.

    Test the sanity of the codebase by performing pre-commit checks. In the dnf5 directory, run the following commands:

    pre-commit install
git add _<your_changes>_
git commit -m "_<your_commit>_"
...
Check the results.

    All checks will run as part of a PR action on GitHub. Therefore, make sure not to skip the checks if you do not want to amend your contribution.

    As part of pre-commit checks, we perform checks such as trailing whitespaces, end of file fixes, clang-format, and rpmlint checks. For more information, see .pre-commit-config.yml.

  • AI-assisted commits must be labeled according to the above AI-assisted contributions policy.