diff options
author | Konstantin Ryabitsev <konstantin@linuxfoundation.org> | 2022-09-14 17:21:57 -0400 |
---|---|---|
committer | Konstantin Ryabitsev <konstantin@linuxfoundation.org> | 2022-09-14 17:21:57 -0400 |
commit | 355bd19d6686fe1df96b7394aaa78aa33b227f47 (patch) | |
tree | 25157c5db442506c9de40f083bc262968cc2d19b | |
parent | 2ce1e619ddb48a4ebda2f4afb39bdcd5baae9a95 (diff) | |
download | b4-355bd19d6686fe1df96b7394aaa78aa33b227f47.tar.gz |
docs: add overview for the contributor section
The hope is to complete the rest tomorrow so we can plan version 0.10.0
release some time in the next short while.
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
-rw-r--r-- | docs/contributor/overview.rst | 71 | ||||
-rw-r--r-- | docs/contributor/prep.rst | 4 | ||||
-rw-r--r-- | docs/contributor/send.rst | 4 | ||||
-rw-r--r-- | docs/contributor/trailers.rst | 4 |
4 files changed, 76 insertions, 7 deletions
diff --git a/docs/contributor/overview.rst b/docs/contributor/overview.rst index 6253da9..a7acd81 100644 --- a/docs/contributor/overview.rst +++ b/docs/contributor/overview.rst @@ -1,4 +1,73 @@ Contributor overview ==================== +Even though b4 started out as a tool to help maintainers, beginning with +the version ``0.10`` there is also a set of features aimed at making it +easier for contributors to submit patch series: -Stub. +* ``b4 prep`` allows to get your patch series ready for sending to the + maintainer for review +* ``b4 send`` simplifies the process of submitting your patches to the + upstream maintainer even if you don't have access to a very good SMTP + server +* ``b4 trailers`` simplifies the process of retrieving code-review + trailers received on the distribution lists and applying them to your + tree + +.. warning:: + + This is a very new set of features and should be considered + experimental. While a lot of work has gone into making sure that your + git tree is not harmed in any way, it is best to always have backups + and to always check things with ``--dry-run`` when that option is + available. + +Do I still need to be able to send email? +----------------------------------------- +While ``b4 send`` makes it possible to submit patches without having +access to an SMTP server, you still need a reasonable mail server for +participating in conversations and code review. + +The main benefit of ``b4 send`` is that you no longer have to really +care if your SMTP server performs some kind of content mangling that +causes patches to become corrupted. + +What is the b4 contributor workflow? +------------------------------------ +The workflow is still very git-oriented, so you should expect to need to +know a lot about such git commands like ``git amend`` and ``git +rebase -i``. In general, the process goes like this: + +1. Prepare your patch series by using ``b4 prep`` and queueing your + commits. Use ``git rebase -i`` to arrange the commits in the right + order and to write good commit messages. + +2. Prepare your cover letter using ``b4 prep --edit-cover``. You should + provide a good overview of what your series does and why you think it + will improve the current code. + +3. When you are almost ready to send, use ``b4 prep --auto-to-cc`` + to collect the relevant addresses from your commits. If your project + uses a ``MAINTAINERS`` file, this will also perform the required + query to figure out who should be included on your patch series + submission. + +4. Review the list of addresses that were added to the cover letter and, + if you know what you're doing, remove any that you think are + unnecessary. + +5. Send your series using ``b4 send``. This will automatically reroll + your series to the next version and add changelog entries to the + cover letter. + +6. Await code review and feedback from maintainers. + +7. Apply any received code-review trailers using ``b4 trailers -u``. + +8. Use ``git rebase -i`` to make any changes to the code based on the + feedback you receive. Remember to record these changes in the cover + letter's changelog. + +9. GOTO 3. + +Please read the rest of these docs for details on the ``prep``, +``send``, and ``trailers`` subcommands. diff --git a/docs/contributor/prep.rst b/docs/contributor/prep.rst index 2d034ef..e7955c2 100644 --- a/docs/contributor/prep.rst +++ b/docs/contributor/prep.rst @@ -1,4 +1,4 @@ -Preparing your patch series -=========================== +prep: preparing your patch series +================================= Stub. diff --git a/docs/contributor/send.rst b/docs/contributor/send.rst index da09547..a9f0a76 100644 --- a/docs/contributor/send.rst +++ b/docs/contributor/send.rst @@ -1,4 +1,4 @@ -Sending in your work -==================== +send: sending in your work +========================== Stub. diff --git a/docs/contributor/trailers.rst b/docs/contributor/trailers.rst index 9e36a8f..2984030 100644 --- a/docs/contributor/trailers.rst +++ b/docs/contributor/trailers.rst @@ -1,4 +1,4 @@ -Retrieving code-review trailers -=============================== +trailers: retrieving code-review trailers +========================================= Stub. |