doc: consolidate contributor guidance into CONTRIBUTING.md

README.md was mixing user-facing content (build instructions,
configuration, distro support) with developer-facing content
(how to add commands, how to add plugins, API naming conventions,
PR workflow). Readers looking to contribute had no obvious starting
point.

Move the three developer-facing sections — "Developers",
"API naming conventions", and "How to contribute" — into
CONTRIBUTING.md, where they join and supersede the existing
commit-conventions and bug-report stubs. Replace all three
sections in README.md with a short "Contributing" paragraph
that links to CONTRIBUTING.md.

While reorganizing CONTRIBUTING.md, document the new API naming
convention (libnvme_/libnvmf_ for libnvme, nvme_/nvmf_ for
nvme-cli) so contributors know which prefix to use when adding
new functions.

Signed-off-by: Martin Belanger <[email protected]>

Author: Martin Belanger

CONTRIBUTING.md

@@ -1,8 +1,8 @@
 <!-- SPDX-License-Identifier: GPL-2.0-only -->
-# Contributing to the NVM-e CLI
+# Contributing to nvme-cli and libnvme
 
 Here you will find instructions on how to contribute to the NVM-Express command
-line interface.
+line interface and the libnvme library.
 
 Contributions and new ideas are most welcome!
 
@@ -14,13 +14,178 @@ under the [GPLv2-style License used for the NVMe CLI](https://github.com/linux-n
 Because there are a few files licensed under GPL-2.0-only, the whole
 project is tagged as GPL-2.0-only and not as GPL-2.0-or-later.
 
-### Code Contributions
+## API naming conventions
 
-Please feel free to use the github forums to ask for comments & questions on
-your code before submitting a pull request.  The NVMe CLI project uses the
-common *fork and merge* workflow used by most GitHub-hosted projects.
+Both components in this repository follow a strict prefix convention so that
+the origin and scope of every symbol is immediately clear to a reader.
 
-#### Commit conventions
+### libnvme
+
+The libnvme library exposes two disjoint sets of public symbols, distinguished
+by their prefix:
+
+| Prefix | Scope | Examples |
+|--------|-------|---------|
+| `libnvme_` | Common NVMe (PCIe and NVMe-oF) | `libnvme_open()`, `libnvme_create_global_ctx()`, `libnvme_first_host()`, `libnvme_ctrl_identify()` |
+| `libnvmf_` | NVMe-oF only | `libnvmf_connect_ctrl()`, `libnvmf_add_ctrl()`, `libnvmf_get_discovery_log()`, `libnvmf_trtype_str()` |
+
+The split is enforced by two separate version scripts: `libnvme/src/libnvme.ld`
+exports all `libnvme_*` symbols, and `libnvme/src/libnvmf.ld` exports all
+`libnvmf_*` symbols. Both scripts are passed to the linker when building
+`libnvme.so`.
+
+> **Note:** NVMe-spec-defined type names (structs and enums that mirror the
+> specification) use the shorter `nvmf_` prefix without the `lib` part (e.g.,
+> `nvmf_disc_log_entry`, `nvmf_discovery_log`). These are data-layout types,
+> not library API functions, and follow the spec naming rather than the library
+> naming convention.
+
+### nvme-cli (the `nvme` executable)
+
+Functions internal to the `nvme` executable follow the same two-prefix rule:
+
+| Prefix | Scope | Examples |
+|--------|-------|---------|
+| `nvme_` | Common NVMe (PCIe and NVMe-oF) | `nvme_show_id_ctrl()`, `nvme_get_log_smart()`, `nvme_identify_ctrl()`, `nvme_show_status()` |
+| `nvmf_` | NVMe-oF only | `nvmf_connect()`, `nvmf_disconnect()`, `nvmf_discover()` |
+
+### Summary
+
+| Component | Common NVMe prefix | NVMe-oF prefix |
+|-----------|--------------------|----------------|
+| libnvme   | `libnvme_`         | `libnvmf_`     |
+| nvme-cli  | `nvme_`            | `nvmf_`        |
+
+When contributing new functions, choose the prefix that matches both the
+component you are modifying and the scope of the functionality:
+- If the function works for both PCIe and NVMe-oF controllers, use the common
+  prefix (`libnvme_` or `nvme_`).
+- If the function is specific to NVMe-oF (fabrics transport, discovery,
+  connect/disconnect), use the NVMe-oF prefix (`libnvmf_` or `nvmf_`).
+
+## Adding commands and plugins
+
+You may wish to add a new command or possibly an entirely new plug-in
+for some special extension outside the spec.
+
+This project provides macros that help generate the code for you. If
+you're interested in how that works, it is very similar to how trace
+events are created by Linux kernel's 'ftrace' component.
+
+### Add a command to the existing built-in
+
+The first thing to do is define a new command entry in the command
+list. This is declared in nvme-builtin.h. Simply append a new "ENTRY" into
+the list. The ENTRY normally takes three arguments: the "name" of the
+subcommand (this is what the user will type at the command line to invoke
+your command), a short help description of what your command does, and the
+name of the function callback that you're going to write. Additionally,
+you can declare an alias name of the subcommand with a fourth argument, if
+needed.
+
+After the ENTRY is defined, you need to implement the callback. It takes
+four arguments: argc, argv, the command structure associated with the
+callback, and the plug-in structure that contains that command. The
+prototype looks like this:
+
+  ```c
+  int f(int argc, char **argv, struct command *command, struct plugin *plugin);
+  ```
+
+The argc and argv are adjusted from the command line arguments to start
+after the sub-command. So if the command line is "nvme foo --option=bar",
+the argc is 1 and argv starts at "--option".
+
+You can then define argument parsing for your sub-command's specific
+options then do some command-specific action in your callback.
+
+### Add a new plugin
+
+The nvme-cli provides macros to make defining a new plug-in simpler. You
+can certainly do all this by hand if you want, but it should be easier
+to get going using the macros. To start, first create a header file
+to define your plugin. This is where you will give your plugin a name,
+description, and define all the sub-commands your plugin implements.
+
+The macros must appear in a specific order within the header file. The following
+is a basic example on how to start this:
+
+File: foo-plugin.h
+```c
+#undef CMD_INC_FILE
+#define CMD_INC_FILE plugins/foo/foo-plugin
+
+#if !defined(FOO) || defined(CMD_HEADER_MULTI_READ)
+#define FOO
+
+#include "cmd.h"
+
+PLUGIN(NAME("foo", "Foo plugin"),
+	COMMAND_LIST(
+		ENTRY("bar", "foo bar", bar)
+		ENTRY("baz", "foo baz", baz)
+		ENTRY("qux", "foo qux", qux)
+	)
+);
+
+#endif
+
+#include "define_cmd.h"
+```
+
+In order to have the compiler generate the plugin through the xmacro
+expansion, you need to include this header in your source file, with
+a pre-defining macro directive to create the commands.
+
+To get started from the above example, we just need to define "CREATE_CMD"
+and include the header:
+
+File: foo-plugin.c
+```c
+#include "nvme.h"
+
+#define CREATE_CMD
+#include "foo-plugin.h"
+```
+
+After that, you just need to implement the functions you defined in each
+ENTRY, then append the object file name to the meson.build "sources".
+
+### Updating the libnvme accessor functions
+
+libnvme exposes auto-generated getter/setter accessor functions for its
+ABI-stable opaque structs. Two sets of accessors are maintained:
+
+| Set | Input header | Generated files |
+|-----|-------------|-----------------|
+| Common NVMe | `libnvme/src/nvme/private.h` | `src/nvme/accessors.{h,c}`, `src/accessors.ld` |
+| NVMe-oF | `libnvme/src/nvme/private-fabrics.h` | `src/nvme/accessors-fabrics.{h,c}`, `src/accessors-fabrics.ld` |
+
+The generated `.h` and `.c` files are committed to the source tree and are
+**not** regenerated during a normal build. To regenerate after modifying a
+`/*!generate-accessors*/` struct:
+
+```shell
+$ meson compile -C .build update-accessors
+```
+
+See [`libnvme/README.md`](libnvme/README.md#accessor-generation) for full
+details, including how to maintain the `.ld` version-script files.
+
+## Submitting changes
+
+There are two ways to send code changes to the project. The first one
+is by sending the changes to [email protected]. The
+second one is by posting a pull request on Github. In both cases
+please follow the Linux contributions guidelines as documented in
+[Submitting patches](https://docs.kernel.org/process/submitting-patches.html).
+
+That means the changes should be a clean series (no merges should be
+present in a Github PR for example) and every commit should build.
+
+See also [How to create a pull request on GitHub](https://opensource.com/article/19/7/create-pull-request-github).
+
+### Commit conventions
 
 The project follows the Linux kernel mailing list workflow,
 thus commit messages should be structured like this:
@@ -42,6 +207,39 @@ Show new contributors the project's commit guidelines
 Signed-off-by: John Doe <[email protected]>
 ```
 
-### Bug Reports
+### How to clean up your series before creating a PR
+
+This example here assumes the changes are in a branch called
+fix-something, which branched away from master in the past. In the
+meantime the upstream project has changed, hence the fix-something
+branch is not based on the current HEAD. Before posting the PR, the
+branch should be rebased on the current HEAD and retest everything.
+
+For example, rebasing can be done by the following steps
+
+```shell
+# Update master branch
+#   upstream == https://github.com/linux-nvme/nvme-cli.git
+$ git switch master
+$ git fetch --all
+$ git reset --hard upstream/master
+
+# Make sure all dependencies are up to date and make a sanity build
+$ meson subprojects update
+$ ninja -C .build
+
+# Go back to the fix-something branch
+$ git switch fix-something
+
+# Rebase it to the current HEAD
+$ git rebase master
+[fixup all merge conflicts]
+[retest]
+
+# Push your changes to Github and trigger a PR
+$ git push -u origin fix-something
+```
+
+## Bug Reports
 
 Bugs for the NVM Library project are tracked in our [GitHub Issues Database](https://github.com/linux-nvme/nvme-cli/issues).