diff options
author | Florian Festi <ffesti@redhat.com> | 2021-07-01 15:33:31 +0200 |
---|---|---|
committer | Panu Matilainen <pmatilai@redhat.com> | 2021-08-20 11:44:09 +0300 |
commit | 8ecefde5777350ef09ad14a5ce3e77ef096720aa (patch) | |
tree | 723a432bda41ba30d4169398c87f6f14ae4d7c13 | |
parent | 44e0e0989b0a4312e5cc5b66833738db3874b1fa (diff) | |
download | rpm-8ecefde5777350ef09ad14a5ce3e77ef096720aa.tar.gz |
Extend CONTRIBUTING.md
Add brief introduction, section about comments and commit messages
Bit more details on code formatting
(cherry picked from commit 3cb4b8b051032d33d1a52f48468cc543d90f7f3c)
-rw-r--r-- | CONTRIBUTING.md | 49 |
1 files changed, 45 insertions, 4 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9acf94b3..7baeb1257 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,59 @@ -# Submitting Patches +# Contributing to RPM -Patches should be submitted via GitHub pull requests (PRs). Each PR should be a +RPM has a history that goes back over two decades and is used by many +different distributions - some providing support for a decade or +more. There are hundreds of thousands RPM packages in use out +there. This makes changes to RPM difficult and they often require thorough +consideration on the implications and on compatibility. + +So while we invite contributions from all sides - especially from the +multitude of RPM based distributions - RPM by its very nature is not an +easy project to get into. + +## Submitting Patches + +Patches should be submitted via GitHub pull requests (PRs) or via `git +send-mail` to the rpm-maint@lists.rpm.org mailing list. Each PR should be a single atomic change, meaning that it should be merged or rejected as a unit. It is okay for a PR to contain multiple commits if later commits are dependent on earlier ones. If earlier commits do not depend on later ones, they (should/should not) be submitted separately. -# Code Style +Pull requests should clearly state if the code is "ready for +inclusion" or if further work is needed. Proof of concept or request +for comment pull requests are fine but need to be labled as such. + +## Comments and Commit Messages + +Information about the change should go into the commit message. This +includes not only what is changed but also why. The commit message needs to +be self contained. While references to GitHub tickets or external bug +trackers are welcome the important information needs to be (also) in +the commit message itself. +For many changes a justification why the change is needed should also +be given in the commit message. + +Comments on the other hand should be used sparingly and for subtle and +non-obvious things only. One-liners are prefered for in-line comments, +unless there is something really special or complicated. Longer +comments can go into the doc strings of functions. But back ground +information should go into the commit message instead. + +## Code Style RPM uses 8-space tabs. Indentation is 4 spaces, with each group of 8 or more -leading spaces replaced by a tab. +leading spaces replaced by a tab. If in doubt, 'indent -kr' generally +produces acceptable formatting. In VIM, this can be achieved with ```vim set shiftwidth=4 tabstop=8 softtabstop=4 ``` + +In emacs use +``` +(setq-default c-basic-offset 4 + indent-tabs-mode t) + +``` |