From 036a411f60c9cc2b1c990fd0d6427a9cde146b34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcus=20M=C3=BCller?= Date: Wed, 15 Feb 2017 17:32:05 +0100 Subject: [PATCH 1/2] 0002: Upstreaming --- gripe-0002-upstreaming.md | 137 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 gripe-0002-upstreaming.md diff --git a/gripe-0002-upstreaming.md b/gripe-0002-upstreaming.md new file mode 100644 index 0000000..60b26c6 --- /dev/null +++ b/gripe-0002-upstreaming.md @@ -0,0 +1,137 @@ +# GRIPE 0002 -- Upstreaming Process + + +- Original Author: Marcus Müller +- Champion: Marcus Müller +- Status: Draft + +History: +- 15-Feb-2017: Initial Draft + + +## Abstract + +This GRIPE strives to establish a guideline for + +* when to submit blocks for becoming part of the upstream GNU Radio tree and +* how to ensure maintenance and maintainability + +## Copyright / License + +[WTFPL](http://www.wtfpl.net/txt/copying/) Version 2 or later + +## Motivation + +GNU Radio calls itself the "Free and Open Software Radio Ecosystem". We're not +doing that bad with ecosystem size, but the code quality in Out-Of-Tree Modules +(OOTs) is very varying, and with every release, we risk serious bitrot, since +there's no "maintained" upstream for any of these -- they are 100% in the care of +their original authors. + +For standalone, self-contained OOTs, this is a fine solution; for utility +modules like the popular gr-foo, this becomes problematic. Also, most authors +just prefer to write the utility blocks they need for themselves, and thus, +these are never seen by other GNU Radio users or OOT authors. + +Compare the Linux Kernel: There's extensive infrastructure within the kernel, +yet code quality is high, and aside from the comparatively rare slip-up, no +kernel gets released that breaks userland or has components that ceased to work. + +The Linux kernel contribution model is centralistic: There's but one kernel. +Sure, you can fork it, add your device drivers to it, and then hope it'll be +forward-portable easily in the future, but the preferred way is to upstream your +code. + +The idea is that as soon as it's upstreamed, the subsystem maintainer has gotten +the responsibility to keep it functional. That way, if anything within the +kernel changes, there's someone with both knowledge and responsibility that will +make your code work with the change. + +In the long run, GNU Radio should come with batteries included -- not a +ready-to-be-used implementation of all possible wireless standards and methods, +but giving its users all the tools known in the GNU Radio ecosystem to maximize +usability. + +## Description + +This document strives to establish a common goal of integrating new +functionality or functional enhancements into the GNU Radio upstream. This +document is not meant to describe the *only* approach on how to contribute to +the GNU Radio main tree; it revolves primarily on adding new blocks to GNU +Radio's main tree. + +If a change goes deep and changes behavior of the runtime / scheduler, this +document does NOT describe the proper way of improving GNU Radio. GNU Radio is a +very community-driven project. Complex changes are best discussed on the mailing +list. + +This document does not apply to bug fixes. + +This document does not apply to documentation enhancements. + +The last word is with the maintainers, as they will take over responsibility and +make the code work in the future. Hence, the criteria below must be understood +as necessary, but not sufficient for upstreaming change. + +### Upstreaming Criteria + +As said above, these are guidelines for *necessary* criteria. The maintainers +are the ones taking care of the code later on -- they can freely choose not to +upstream any changes that they feel incapable of maintaining, contradict goals +of the project, or simply do not fit their opinion of what should be part of the +main tree or not. + +#### Objective + +The objective is to make reusable, high-quality, useful code part of the +Runtime, and keep it there. + +#### Legal Criteria + +TODO + +#### High reusability + +* I.e. implementations of specific standards are NOT ELIGIBLE for upstreaming +* Basic math operations are ELIGIBLE +* Widely adopted algorithms are ELIGIBLE +* Additions / Modifications to the overall operation of GNU Radio and its runtime / scheduler are ELIGIBLE + +Here, subjective judgment of the maintainers is especially relevant and can +overrule any concern given above or in the community. + +Good reasons to *not* upstream change is that certain things are really better +off in an out-of-tree module. + +#### Code Quality / Maintainability + +Gripe 0001 applies without any restriction. Objective is to make new code stand +out in quality. + +The community strives to maintain reference to an official tool to check patches +for conformity to coding style guidelines (compare checkpatch of the Linux +kernel). + +### Upstreaming Process + +1. The party interested in upstreaming MUST integrate their changes into a fork + of GNU Radio on a publicly available git repository (classically: Github), + based on the HEAD of either the current "master" or "next" branch. The branch + name MUST be descriptive of the proposed change. +2. The party MUST write an email to the discuss-gnuradio@gnu.org mailing list + from the email address used as author in the commits. + If there's multiple git authors, one of these email addresses SHALL be used, + informing the community of + * The existence and URL of their fork, + * the purpose of the change, + * the name of the branch, + * the scope of the changes. +3. If necessary, FSF copyright assignment agreements MUST be arranged +4. During the process of upstreaming, the original author(s) SHALL offer a + reliable contact. The process consists of + * Community and Maintainer review of the changes + * Feedback by the Maintainer + * Working said feedback back into the proposed changeset +5. The GNU Radio release manager, upon completion of merging the new + functionality, SHALL add a remark describing the change to the GNU Radio + CHANGELOG From 09bd636668dbc4583d615e86f9fabccbdf0237df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcus=20M=C3=BCller?= Date: Mon, 5 Mar 2018 13:51:34 +0100 Subject: [PATCH 2/2] Conversion to GREP process This not only includes replacing all occurences of GRIPE by GREP, but also adopting the GREP process as preferred way of bringing in substantial change to the environment. --- ...upstreaming.md => grep-000x-upstreaming.md | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) rename gripe-0002-upstreaming.md => grep-000x-upstreaming.md (88%) diff --git a/gripe-0002-upstreaming.md b/grep-000x-upstreaming.md similarity index 88% rename from gripe-0002-upstreaming.md rename to grep-000x-upstreaming.md index 60b26c6..f040bc5 100644 --- a/gripe-0002-upstreaming.md +++ b/grep-000x-upstreaming.md @@ -1,17 +1,17 @@ -# GRIPE 0002 -- Upstreaming Process +# GREP [XXXX] -- Upstreaming Process -- Original Author: Marcus Müller -- Champion: Marcus Müller -- Status: Draft +- Original Author: Marcus Müller +- Champion: Marcus Müller +- Status: Draft History: - 15-Feb-2017: Initial Draft - +- 05-Mar-2018: Conversion to GREP process ## Abstract -This GRIPE strives to establish a guideline for +This GREP+ strives to establish a guideline for * when to submit blocks for becoming part of the upstream GNU Radio tree and * how to ensure maintenance and maintainability @@ -63,7 +63,7 @@ Radio's main tree. If a change goes deep and changes behavior of the runtime / scheduler, this document does NOT describe the proper way of improving GNU Radio. GNU Radio is a very community-driven project. Complex changes are best discussed on the mailing -list. +list, and especially in the form of GREPs. This document does not apply to bug fixes. @@ -88,14 +88,17 @@ Runtime, and keep it there. #### Legal Criteria -TODO +The Copyright Requirements of the GNU Radio Project have to be met. That means, +at this time, that the author of code needs to assign copyright to the FSF. -#### High reusability +#### High Reusability * I.e. implementations of specific standards are NOT ELIGIBLE for upstreaming * Basic math operations are ELIGIBLE * Widely adopted algorithms are ELIGIBLE -* Additions / Modifications to the overall operation of GNU Radio and its runtime / scheduler are ELIGIBLE +* Adapters to commonly used external tools are ELIGIBLE +* Additions / Modifications to the overall operation of GNU Radio and its + runtime / scheduler are ELIGIBLE Here, subjective judgment of the maintainers is especially relevant and can overrule any concern given above or in the community. @@ -105,8 +108,8 @@ off in an out-of-tree module. #### Code Quality / Maintainability -Gripe 0001 applies without any restriction. Objective is to make new code stand -out in quality. +GREP0001 (Coding Guidelines) applies without any restriction. Objective is to +make new code stand out in quality. The community strives to maintain reference to an official tool to check patches for conformity to coding style guidelines (compare checkpatch of the Linux