diff mbox series

[RFC] blog post: how to get your new feature up-streamed

Message ID 20211126203319.3298089-1-alex.bennee@linaro.org
State New
Headers show
Series [RFC] blog post: how to get your new feature up-streamed | expand

Commit Message

Alex Bennée Nov. 26, 2021, 8:33 p.m. UTC 
Experience has shown that getting new functionality up-streamed can be
a somewhat painful process. Lets see if we can collect some of our
community knowledge into a blog post describing some best practices
for getting code accepted.

[AJB: obviously RFC for now, need material for the end]

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 ...26-so-you-want-to-add-something-to-qemu.md | 100 ++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 _posts/2021-11-26-so-you-want-to-add-something-to-qemu.md

Comments

Ján Tomko Dec. 10, 2021, 10:51 a.m. UTC | #1 
On a Friday in 2021, Alex Bennée wrote:
>Experience has shown that getting new functionality up-streamed can be
>a somewhat painful process. Lets see if we can collect some of our
>community knowledge into a blog post describing some best practices
>for getting code accepted.
>
>[AJB: obviously RFC for now, need material for the end]
>
>Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>---
> ...26-so-you-want-to-add-something-to-qemu.md | 100 ++++++++++++++++++
> 1 file changed, 100 insertions(+)
> create mode 100644 _posts/2021-11-26-so-you-want-to-add-something-to-qemu.md
>
>diff --git a/_posts/2021-11-26-so-you-want-to-add-something-to-qemu.md b/_posts/2021-11-26-so-you-want-to-add-something-to-qemu.md
>new file mode 100644
>index 0000000..d38c0ca
>--- /dev/null
>+++ b/_posts/2021-11-26-so-you-want-to-add-something-to-qemu.md

[..]

>+The maintainers path
>+====================
>+

[..]

>+I won't pretend there isn't some commitment required when becoming a
>+maintainer. However if you were motivated enough to write the code for
>+a new feature you should be up to keeping it running smoothly in the
>+upstream. The level of effort required is also proportional to the
>+popularity of the feature - there is a world of difference between
>+maintaining an individual device and a core subsystem. If the feature
>+

Unfinished sentence.

>+Practically you will probably want to get yourself a
>+[GitLab](https://gitlab.com/qemu-project/qemu/-/blob/master/MAINTAINERS)
>+account so you can run the CI tests on your pull requests. While
>+membership of `qemu-devel` is recommended no one is expecting you to
>+read every message sent to it as long as you look at those where you
>+are explicitly Cc'd.
>+
>+Now if you are convinced to become a maintainer for your new feature
>+lets discuss how you can improve the chances of getting it merged.
>+

* let's

Jano
diff mbox series

Patch

diff --git a/_posts/2021-11-26-so-you-want-to-add-something-to-qemu.md b/_posts/2021-11-26-so-you-want-to-add-something-to-qemu.md
new file mode 100644
index 0000000..d38c0ca
--- /dev/null
+++ b/_posts/2021-11-26-so-you-want-to-add-something-to-qemu.md
@@ -0,0 +1,100 @@ 
+---
+layout: post
+title:  "So you want to add a sub-system/device/architecture to QEMU?"
+date:   2021-11-26 19:43:45
+author: Alex Bennée
+categories: [blog, process, development]
+---
+
+From time to time I hear of frustrations from potential new
+contributors who have tried to get new features up-streamed into the
+QEMU repository. After having read [our patch
+guidelines](https://qemu.readthedocs.io/en/latest/devel/submitting-a-patch.html)
+they post them to [qemu-devel](https://lore.kernel.org/qemu-devel/).
+Often the patches sit there seemingly unread and unloved. The
+developer is left wandering if they missed out the secret hand shake
+required to move the process forward. My hope is that this blog post
+will help.
+
+
+New features != Fixing a bug
+============================
+
+Adding a new feature is not the same as fixing a bug. For an area of
+code that is supported for Odd Fixes or above there will be a
+someone listed in the
+[MAINTAINERS](https://gitlab.com/qemu-project/qemu/-/blob/master/MAINTAINERS)
+file. A properly configured `git-send-email` will even automatically
+add them to the patches as they are sent out. The maintainer will
+review the code and if no changes are requested they ensure the 
+patch flows through the appropriate trees and eventually makes it into
+the master branch.
+
+This doesn't usually happen for new code unless your patches happen to
+touch a directory that is marked as maintained. Without a maintainer
+to look at and apply your patches how will it ever get merged?
+
+Adding new code to a project is not a free activity. Code that isn't
+actively maintained has a tendency to [bit
+rot](http://www.catb.org/jargon/html/B/bit-rot.html) and become a drag
+on the rest of the code base. The QEMU code base is quite large and
+none of the developers are knowledgeable about the all of it. If
+features aren't
+[documented](https://qemu.readthedocs.io/en/latest/devel/submitting-a-patch.html)
+they tend to remain unused as users struggle to enable them. If an
+unused feature becomes a drag on the rest of the code base by preventing
+re-factoring and other clean ups it is likely to be deprecated.
+Eventually deprecated code gets removed from the code base never to be
+seen again.
+
+Fortunately there is a way to avoid the ignominy of ignored new features
+and that is to become a maintainer of your own code!
+
+The maintainers path
+====================
+
+There is perhaps an unfortunate stereotype in the open source world of
+maintainers being grumpy old experts who spend their time dismissively
+rejecting the patches of new contributors. Having done their time in
+the metaphorical trenches of the project they must ingest the email
+archive to prove their encyclopedic mastery. Eventually they then
+ascend to the status of maintainer having completed the dark key
+signing ritual.
+
+In reality the process is much more prosaic - you simply need to send
+a patch to the MAINTAINERS file with your email address, the areas you
+are going to cover and the level of support you expect to give.
+
+I won't pretend there isn't some commitment required when becoming a
+maintainer. However if you were motivated enough to write the code for
+a new feature you should be up to keeping it running smoothly in the
+upstream. The level of effort required is also proportional to the
+popularity of the feature - there is a world of difference between
+maintaining an individual device and a core subsystem. If the feature 
+
+Practically you will probably want to get yourself a
+[GitLab](https://gitlab.com/qemu-project/qemu/-/blob/master/MAINTAINERS)
+account so you can run the CI tests on your pull requests. While
+membership of `qemu-devel` is recommended no one is expecting you to
+read every message sent to it as long as you look at those where you
+are explicitly Cc'd.
+
+Now if you are convinced to become a maintainer for your new feature
+lets discuss how you can improve the chances of getting it merged.
+
+A practically perfect set of patches
+====================================
+
+I don't want to repeat all the valuable information from the
+submitting patches document but I do want to emphasise the importance
+of responding to comments and collecting review and testing tags.
+
+While it usual to expect a maintainer `Reviewed-by` or `Acked-by` tags for any
+patches that touches another sub-system there is still the problem of
+getting reviews for your brand new code. Fortunately there is no
+approved reviewer list for QEMU. The purpose of review is to show that
+someone else has at least applied the patches and run the code. Even
+if they are not confident in reviewing the source a `Tested-by` tag
+gives confidence that the code works.
+
+<TBC - solicit feedback from the list>