From 0b198f2fff08b54fa636b14804f618e0693cdb0e Mon Sep 17 00:00:00 2001 From: Jeremy Cline Date: Thu, 19 Mar 2020 19:52:16 +0000 Subject: [PATCH] Update Contributor Guide --- Contributor-Guide.md | 107 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 85 insertions(+), 22 deletions(-) diff --git a/Contributor-Guide.md b/Contributor-Guide.md index dd0feb7..c579b12 100644 --- a/Contributor-Guide.md +++ b/Contributor-Guide.md @@ -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 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 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//` 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 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: `. 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 +``` + +## 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. -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 my-kernel-patch`` \ No newline at end of file +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 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. \ No newline at end of file