Update Contributor Guide
Jeremy Cline
parent
4c899ffe98
commit
0b198f2fff
@ -1,36 +1,99 @@
|
||||
General contribution guidelines are covered in https://docs.fedoraproject.org/en-US/quick-docs/kernel/overview/#_policies
|
||||
|
||||
# ARK Contributor's Guide
|
||||
Thanks for considering contributing to the Fedora and Always Ready kernels, we really appreciate it! Before you get started, please familiarize yourself with the general [Fedora kernel policies](https://docs.fedoraproject.org/en-US/quick-docs/kernel/overview/#_policies).
|
||||
|
||||
These guides assume you've completed the [setup guide](https://gitlab.com/cki-project/kernel-ark/-/wikis/home#setup) and are familiar with the [repository layout](Repository-layout).
|
||||
|
||||
There are two major types of contributions ARK accepts. The first is kernel configuration options and build scripts, both of which live in the ``internal`` branch. The second are patches to the kernel itself, which are in ``ark-patches``.
|
||||
There are two major types of contributions ARK accepts. The first is kernel configuration options and build scripts, both of which live in the ``internal`` branch. The second are patches to the kernel itself, which are in the ``ark-patches`` branch.
|
||||
|
||||
## Configuration, Build Scripts, and Specfile
|
||||
|
||||
Start a new branch based on ``internal``:
|
||||
Quick start:
|
||||
|
||||
1. ``git fetch upstream``
|
||||
2. ``git checkout -b my-build-change upstream/internal``
|
||||
3. Make a change to a file or files in ``redhat/``.
|
||||
4. Add your changes with ``git add -A``.
|
||||
5. Commit your changes and write a nice commit message that explains the change: ``git commit -s``.
|
||||
6. Open a merge request: ``git push -o merge_request.create -o merge_request.target=internal -o merge_request.remove_source_branch -u <your-remote> my-build-change``
|
||||
1. `git fetch upstream`
|
||||
2. `git checkout -b my-build-change upstream/internal`
|
||||
3. Make a change to a file or files in `redhat/`.
|
||||
4. Add your changes with `git add -A`.
|
||||
5. Commit your changes and write a nice commit message that explains the change: `git commit -s`.
|
||||
6. Open a merge request: `git push -o merge_request.create -o merge_request.target=internal -o merge_request.remove_source_branch -u <your-remote> my-build-change`
|
||||
|
||||
## Fedora Kernel Patches
|
||||
### Configuration Changes
|
||||
|
||||
To add or update a kernel patch carried for Fedora, start a new branch based on ``fedora-patches``:
|
||||
Each configuration option for the kernel is placed in its own file inside the `redhat/configs/<flavor>/` directory.
|
||||
|
||||
1. ``git fetch upstream``
|
||||
2. ``git checkout -b my-kernel-patch upstream/fedora-patches``
|
||||
3. Add any commits you like.
|
||||
4. Open a merge request against ``fedora-patches``: ``git push -o merge_request.create -o merge_request.target=fedora-patches merge_request.remove_source_branch -u <your-remote> my-kernel-patch``
|
||||
Each file must be named after the configuration option it contains.
|
||||
|
||||
## ARK Kernel Patches
|
||||
To disable a particular setting, the file must contain `# CONFIG_TOWEL is not set` rather than `CONFIG_TOWEL=n` where CONFIG_TOWEL is replaced with the actual configuration option.
|
||||
|
||||
The directory is hierarchical by architecture families. The top level is generic configurations that apply across most architectures. Within that, there are directories like `arm`, `powerpc`, and `x86` where architecture specific configurations are placed. Settings in these architecture-specific directories override any duplicate settings in the more generic directories. Configurations that are specific to a particular architecture should be placed in that architecture's directory rather in the generic directory.
|
||||
|
||||
Configuration changes in the `common` and `ark` directories require review from Red Hat kernel developers, where-as the configurations in `fedora` can be changed with the approval of the Fedora kernel maintainers.
|
||||
|
||||
### Commit messages
|
||||
|
||||
Each commit you make should contain a detailed description of *why* the change is necessary. For example, if the commit enables or disables a configuration option, explain exactly why the change is necessary. If there is a Bugzilla bug relating to the change, please include a reference to it using the format `Bugzilla: <url>`. For example:
|
||||
|
||||
```
|
||||
Enable CONFIG_TOWEL so kernels never panic
|
||||
|
||||
Since the beginning the kernel has panicked. This has made a lot of people very
|
||||
angry and has widely been regarded as a bad move. This new configuration option
|
||||
solves all the kernel's problems and now it never panics.
|
||||
|
||||
Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1234567890
|
||||
Signed-off-by: Jeremy Cline <jcline@redhat.com>
|
||||
```
|
||||
|
||||
## Kernel Patches
|
||||
|
||||
To add or update a kernel patch carried for ARK, start a new branch based on ``ark-patches``:
|
||||
|
||||
1. ``git fetch upstream``
|
||||
2. ``git checkout -b my-kernel-patch upstream/ark-patches``
|
||||
3. Add any commits you like.
|
||||
1. `git fetch upstream`
|
||||
2. `git checkout -b my-kernel-patch upstream/ark-patches`
|
||||
3. Add any commits you like. These patches should already be submitted upstream and should, ideally, already be accepted in at least a sub-system maintainer's tree.
|
||||
4. Open a merge request against ``ark-patches``: ``git push -o merge_request.create -o merge_request.target=ark-patches merge_request.remove_source_branch -u <your-remote> my-kernel-patch``
|
||||
|
||||
|
||||
## Licensing
|
||||
|
||||
Your commit messages must include a Signed-off-by tag with your name and e-mail
|
||||
address, indicating that you agree to the [Developer Certificate of Origin](
|
||||
https://developercertificate.org/) version 1.1:
|
||||
|
||||
Developer Certificate of Origin
|
||||
Version 1.1
|
||||
|
||||
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
|
||||
1 Letterman Drive
|
||||
Suite D4700
|
||||
San Francisco, CA, 94129
|
||||
|
||||
Everyone is permitted to copy and distribute verbatim copies of this
|
||||
license document, but changing it is not allowed.
|
||||
|
||||
|
||||
Developer's Certificate of Origin 1.1
|
||||
|
||||
By making a contribution to this project, I certify that:
|
||||
|
||||
(a) The contribution was created in whole or in part by me and I
|
||||
have the right to submit it under the open source license
|
||||
indicated in the file; or
|
||||
|
||||
(b) The contribution is based upon previous work that, to the best
|
||||
of my knowledge, is covered under an appropriate open source
|
||||
license and I have the right under that license to submit that
|
||||
work with modifications, whether created in whole or in part
|
||||
by me, under the same open source license (unless I am
|
||||
permitted to submit under a different license), as indicated
|
||||
in the file; or
|
||||
|
||||
(c) The contribution was provided directly to me by some other
|
||||
person who certified (a), (b) or (c) and I have not modified
|
||||
it.
|
||||
|
||||
(d) I understand and agree that this project and the contribution
|
||||
are public and that a record of the contribution (including all
|
||||
personal information I submit with it, including my sign-off) is
|
||||
maintained indefinitely and may be redistributed consistent with
|
||||
this project or the open source license(s) involved.
|
||||
|
||||
Use `git commit -s` to add the Signed-off-by tag.
|
||||
Loading…
Reference in New Issue
Block a user