mirror: Rework README.md file

Improve the README.md on various aspects: - Move the synchronisation details to the end of the file. Extend them a little, remove the mention of "gory details". - Add admonition about using the GitHub mirror repository for building and packaging. Rework the section on BPF/bpftool questions. - Move CI build badge to the main heading. - Add badges for licenses - Fix phrasing for the licensing subsection. This is somewhat aligned with the evolution of libbpf's README.md. Signed-off-by: Quentin Monnet <quentin@isovalent.com>
libbpf · Oct 16, 2023 · e854f13 · e854f13
1 parent 79cc66c
commit e854f13
Showing 1 changed file with 59 additions and 25 deletions.
diff --git a/README.md b/README.md
@@ -1,37 +1,49 @@
 bpftool
+[![License BSD 2-Clause][bsd-badge]](LICENSE.BSD-2-Clause)
+[![License GPL 2.0][gpl-badge]](LICENSE.GPL-2.0)
+[![Build status][build-badge]][build]
 =======
 
-This is a mirror of [bpf-next Linux source tree's
-`tools/bpf/bpftool`](https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/tree/tools/bpf/bpftool)
-directory, plus its few dependencies from under `kernel/bpf/`, and its
-supporting header files.
+[bsd-badge]: https://img.shields.io/badge/License-BSD_2--Clause-blue.svg
+[gpl-badge]: https://img.shields.io/badge/License-GPL_2.0-blue.svg
+[build-badge]: https://github.com/libbpf/bpftool/actions/workflows/build.yaml/badge.svg
+[build]: https://github.com/libbpf/bpftool/actions/workflows/build.yaml
 
-All the gory details of syncing can be found in `scripts/sync-kernel.sh`
-script.
+This is the official home for bpftool. _Please use this Github repository for
+building and packaging bpftool and when using it in your projects through Git
+submodule._
 
-Some header files in this repo (`include/linux/*.h`) are reduced versions of
-their counterpart files at
-[bpf-next](https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/)'s
-`tools/include/linux/*.h` to make compilation successful.
+The _authoritative source code_ of bpftool is developed as part of the
+[bpf-next Linux source tree][bpf-next] under [the `tools/bpf/bpftool`
+subdirectory][tools-bpf-bpftool] and is periodically synced to
+<https://github.com/libbpf/bpftool> on Github. As such, all changes for bpftool
+**should be sent to the [BPF mailing list][bpf-ml]**, **please don't open PRs
+here** unless you are changing some Github-specific components.
 
-BPF/bpftool usage and questions
--------------------------------
+[bpf-next]: https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git
+[tools-bpf-bpftool]: https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/tree/tools/bpf/bpftool
+[bpf-ml]: http://vger.kernel.org/vger-lists.html#bpf
 
-Please check out [the manual pages](docs) for documentation about bpftool. A
-number of example invocations are also displayed in [this blog
+Questions on bpftool and BPF general usage
+------------------------------------------
+
+Check out [the manual pages](docs) for documentation about bpftool. A number of
+example invocations are also displayed in [this blog
 post](https://qmonnet.github.io/whirl-offload/2021/09/23/bpftool-features-thread/).
 
 All general BPF questions, including kernel functionality, bpftool features and
 usage, should be sent to bpf@vger.kernel.org mailing list. You can subscribe to
-it [here](http://vger.kernel.org/vger-lists.html#bpf) and search its archive
-[here](https://lore.kernel.org/bpf/). Please search the archive before asking
-new questions. It very well might be that this was already addressed or
-answered before.
+it [here][bpf-ml] and search its archives [here][lore].
+
+The mailing list is monitored by many more people than this repo and they will
+happily try to help you with whatever issue you encounter. This repository's
+PRs and issues should be opened only for dealing with issues related to
+components specific to the bpftool mirror repository (such as the
+synchronization script or the CI workflows). The project maintainers also use
+GitHub issues as a generic tracker for bpftool, but issues should first be
+reported on the mailing list nonetheless.
 
-bpf@vger.kernel.org is monitored by many more people and they will happily try
-to help you with whatever issue you have. This repository's PRs and issues
-should be opened only for dealing with issues pertaining to specific way this
-bpftool mirror repo is set up and organized.
+[lore]: https://lore.kernel.org/bpf/
 
 Dependencies
 ------------
@@ -50,7 +62,6 @@ Optional:
 - clang/LLVM (idem)
 
 Build
-[![build](https://github.com/libbpf/bpftool/actions/workflows/build.yaml/badge.svg)](https://github.com/libbpf/bpftool/actions/workflows/build.yaml)
 -----
 
 ### Initialize libbpf submodule
@@ -157,10 +168,33 @@ $ cd docs
 # make install
 ```
 
+bpf-next to GitHub sync
+-----------------------
+
+This repository mirrors [bpf-next Linux source tree's
+`tools/bpf/bpftool`][tools-bpf-bpftool] directory, plus its few dependencies
+from under `kernel/bpf/`, and its supporting header files. Some of these header
+files, `include/linux/*.h` on the current repository, are reduced versions of
+their counterpart files at [bpf-next][bpf-next]'s `tools/include/linux/*.h` to
+make compilation successful.
+
+Synchronization between the two repositories happens every few weeks or so.
+Given that bpftool remains aligned on libbpf's version, its repository tends to
+follow libbpf's. When the libbpf repo syncs up with bpf-next, bpftool's repo
+usually follows within the next few days.
+
+The synchronization process is semi-automated: the script in
+`scripts/sync-kernel.sh` cherry-picks, adjusts and commits all changes from
+`bpf-next` to a local version of the bpftool repository. However, maintainers
+run this script manually and then create a pull request to merge the resulting
+commits.
+
+Take a look at [the script](scripts/sync-kernel.sh) for the technical details. of the process. See also the documentation in [the accompanying README.md](scripts#sync-kernelsh)
+
 License
 -------
 
-This work is dual-licensed under the GNU GPL v2.0 (only) license and the
-BSD 2-clause license. You can choose between one of them if you use this work.
+This work is dual-licensed under the GNU GPL v2.0 (only) license and the BSD
+2-clause license. You can select either of them if you reuse this work.
 
 `SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)`