= Contributing to CentOS Stream =

== Before you start writing code... ==

...we would like to thank you for your interest in contributing to CentOS Stream. Though we cannot accommodate all the code — [[https://access.redhat.com/articles/rhel8-abi-compatibility|Red Hat Enterprise Linux 8 provides]] compatibility within a major release of the distribution which needs to be preserved. You can always [[https://bugzilla.redhat.com/enter_bug.cgi|open a bugzilla]] first and discuss with the respective RHEL package maintainers if your change has a chance to be accepted. As with any open source projects, in the end it's up to maintainers to decide which changes they want to accept and maintain, so Red Hat maintainers can decline contributions for any reason.

At the same time, you should always propose your change first to a respective upstream project and Fedora Linux — changes proposed to CentOS Stream should be already accepted in upstream and Fedora before having them in CentOS Stream.

And lastly, as a minor release of RHEL goes through various stages of development, changes may be postponed for a next iteration — once you get a review of your change, the respective maintainer should inform you about further steps.


== Accounts ==
If you want to contribute to CentOS Stream, you need to have an account in [[https://accounts.centos.org/|CentOS FAS]].

== Getting the repository ==
Once your account is set up, you can proceed to clone the respective package repository locally. The package repositories are right now located in two places:

1. [[https://git.centos.org/projects/rpms/%2A|dist-git repositories]]

2. [[https://git.stg.centos.org/projects/source-git/%2A|source-git repositories]]

Contributions via [[Contribute/CentOSStream/SourceGit|source-git]] are still being worked on so please be kind if things are not working as you expect - we'd be happy to get your feedback and improve. Please reach out if you have a question: either to [[https://packit.dev/#contact|the packit team]] or centos-devel@centos.org.


=== Fork & clone ===

Once you located the repository in the web interface, fork it and clone it.

dist-git:
{{{#!bash
$ git clone ssh://git@git.centos.org/forks/$user/rpms/rpm.git
}}}

source-git:
{{{#!bash
$ git clone ssh://git@git.stg.centos.org/forks/$user/source-git/rpm.git
}}}

Don’t forget to set up the upstream remote for the main repository (NOT upstream project):

dist-git:
{{{#!bash
$ git remote add upstream ssh://git@git.centos.org/rpms/rpm.git
}}}

source-git:
{{{#!bash
$ git remote add upstream ssh://git@git.stg.centos.org/source-git/rpm.git
}}}

Once cloned locally, you should check out the `c8s` branch. If there is no such branch, locate `c8` - this means there are no CentOS Stream changes and the package is tracking latest CentOS Linux 8 release.


== Creating a change ==
This is the part where you can shine! There are two types of changes you can make:

1. Change the source code

2. Change packaging (spec file, additional sources such as downstream configuration files)

=== Submitting a pull request ===

We are using the standard git workflow you may know from upstream open source projects:
 * Create a new local git branch
 * Commit the change (if you are backporting a commit from upstream, please keep the upstream commit messages if possible)
 * Push the branch to your fork
 * And finally open a pull request via Pagure web interface

=== Dist-git vs. Source-git ===
If you’re familiar with how packaging is done in CentOS and Fedora, you may know dist-git repositories: each repository represents a source RPM package and contains all the RPM source files (RPM spec file, upstream tarball checksum and optionally patch files and other files). But the repository itself doesn't contain source code - you need to execute %prep phase to see it.

With [[Contribute/CentOSStream/SourceGit|source-git]], the sources are unpacked and downstream changes are layered on top as additional commits. The repositories don't contain upstream git history now, instead we are unpacking an archive for the corresponding upstream release and this is the first commit. For more details on how to work in a source-git repository, please head on to [[https://packit.dev/docs/source-git/work-with-source-git/|packit's documentation]].

It's up to you to pick the preferred way of contributing: both dist-git and source-git are fine.

=== Submitting a change in a source-git repo ===
If you want to update packaging files (in SPECS directory), you can go ahead and change them - no special care is needed.

==== Changing source code by defining the patch in a spec file ====
Creating source code changes needs a bit more work. Packages are modified in CentOS Stream by creating patch files and defining those patches in a spec file. The patches are then applied during a build process in a %prep section.

If you are changing source code and you know that a patch in the spec is needed, add the patch to the spec file with a name of your choice:
{{{
Patch123: my-special-change.patch
}}}

Now you need to annotate commit message with the respective change
{{{
We need this change in CentOS Stream

patch_name: my-special-change.patch
present_in_specfile: true

Signed-off-by: Tomas Tomecek <ttomecek@redhat.com>
---
 src/code.c | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)
}}}

The automation, packit, then reads the commit message, knows that the patch is already defined in the spec and creates a patch file with the name set in "patch_name" from the respective commit when creating a SRPM.

This is the preferred way of changing source code since you are in full control of the process. 

==== Changing source code: packit takes care of patches ====

If packit does not find such metadata as defined above in a commit message:

 1. it adds a new patch entry in the spec file

 2. and generates a patch file from the respective commit

This is convenient but prone to errors. In case this method does not work, please set the metadata as described in the method above.


=== Submitting a change in a dist-git repo ===

The situation here is similar: packaging changes can be done directly, these files can be found in directories SOURCES and SPECS.

If you want to change source code, it's significantly different than doing this with source-git:
 1. the change has to be captured as a patch file
 2. the patch needs to be present in SOURCES directory
 3. and referenced in a spec file correctly (please make sure it applies cleanly)


=== After a pull request is created ===

When you submit a pull request for source-git, automation will pick up the change and build it - there will be RPMs with your change available so you can try them out or just make sure it builds fine.

Once your change is accepted, it will be marked with the label "accepted". Our automation will create a corresponding bugzilla with the patch attached and then it’s up to the RHEL maintainer to pick it up, commit and build internally so that it can land back into CentOS Stream - this process can take some time, so please be patient.


== Get a review ==
In order for your change to land in RHEL and CentOS Stream, it needs to be reviewed and approved by the RHEL maintainer for the particular component. We are making sure behind the scenes they see your patch. If you are not getting any feedback feel free to reach out to #centos-devel on freenode.


== Rebase ==
As new changes are coming to CentOS Stream, there may be a need to rebase your pull request.