diff --git a/seed/0122-code-samples.rst b/seed/0122-code-samples.rst new file mode 100644 index 0000000000..e884cd8b38 --- /dev/null +++ b/seed/0122-code-samples.rst @@ -0,0 +1,209 @@ +.. _seed-0122: + +=================================== +0122: Organize Pigweed code samples +=================================== +.. seed:: + :number: 122 + :name: Organize Pigweed code samples + :status: open_for_comments + :proposal_date: 2024-01-09 + :cl: 187121 + :facilitator: Kayce Basques + +------- +Summary +------- +This SEED describes how Pigweed code samples will be organized. + +---------- +Motivation +---------- +Pigweed users need to see code samples that demonstrate Pigweed in action. +However, there are a few different use cases for such code samples. +Historically, we've not been explicit about what the use cases are, and how +they should be served. This SEED will fill this gap. + +-------- +Proposal +-------- + +Repositories +============ +Pigweed will maintain the following types of code sample repositories: + +* **Quickstart**: `minimal, complete, reproducible + `_ projects you + can clone to understand the basics of Pigweed and start a new `greenfield + project `_. There will be + one Quickstart repository for each build system that Pigweed supports. +* **Examples**: granular, comprehensive code examples of every Pigweed + module's API. The Examples repository can also demonstrate core use cases + that require using multiple modules together. There will only be one Examples + repository. +* **Showcase**: Showstopper examples that demonstrate how to use Pigweed + to implement complex real-world applications. There will be many Showcase + repositories, each demonstrating a different application. These repositories + should inspire users, show them how to implement complex integrations, and + convince them that Pigweed is the best way to develop embedded projects. + +Standard board +============== +The Quickstart and Examples repositories will eventually focus on a single +:ref:`seed-0122-standard-board`. But selecting the standard board is out of the +scope of this SEED. + +--------------- +Detailed design +--------------- + +.. _seed-0122-quickstart: + +Quickstart repository +===================== +* **User journeys** these repositories serve: + + * "I want to clone a minimal repository to create my own project from + scratch." + * "I want to understand the smallest set of steps needed to add Pigweed as a + dependency of my own existing project." + * "I'm just getting started with Pigweed and want a tutorial that will + put *some* code on device". + +* **Repository contents**: One repository per build system that demonstrates + the minimal set of Pigweed features: + + #. Bootstrapping (downloading required tools, third-party dependencies, etc). + #. Building the minimal, viable, complete (MVC) application for + :ref:`target-host` and for the :ref:`seed-0122-standard-board`. + #. Flashing the application to the board. + #. Communicating with the board via :ref:`module-pw_console`. + + Determining the exact content of the MVC app is out-of-scope for this SEED. + This is the subject of `SEED-0106 + `_. + However, every Quickstart repository will implement the same set of MVC + features. + + There will be tutorial documentation associated with each of these + repositories, but it will be hosted in pigweed.git. Documentation generation + with :ref:`module-pw_docgen` falls outside the scope of Quickstart. + + We may also add separate Quickstart repositories for boards other than the + "standard board". + +* **Locations**: + + * https://pigweed.googlesource.com/pigweed/quickstart/bazel.git + * https://pigweed.googlesource.com/pigweed/quickstart/gn.git + * (No CMake quickstart. We offer support for integrating Pigweed into an + existing CMake project, but don't recommend CMake for a greenfield Pigweed + project and so have no quickstart repository for it.) + +.. _seed-0122-examples: + +Examples repository +=================== +* **User journeys** this repository serves: + + * "I want to see an example of how a module's API is used in the context of a + full, building project." + * "I want to use tokenized logging, how do I hook this up?" + * "I read you can customize the :ref:`module-pw_console`, can I see an example?" + * "I want to see how to configure a backend of this module." + * "How do I use method X from Pigweed module Y?" + * "How do I use Pigweed modules A and B together?" + +* **Repository contents**: One repository that contains a bunch of directories. + Each directory is meant to be consulted in isolation. Common use cases such + as logging over UART or blinking an LED, may get their own directories. + Related examples (e.g., examples for an individual module) may be grouped + into a directory hierarchy for clarity. + + The individual examples may define their own build targets, but they are not + expected to set up independent builds. They're all part of one top-level build. + + In general, it should be possible to build the examples using all of + Pigweed's supported build systems (Bazel, CMake, GN). However, if the + functionality being exemplified is only supported in some build systems (e.g. + :ref:`module-pw_docgen` is only supported in GN as of this writing), then its + examples can be restricted to those build systems. + + Unlike Quickstart, this repository is a reference work: the user is not + expected to read through it "from beginning to end". Rather, they will come + here to view a specific example. We eventually expect to have hundreds or + even thousands of examples. + + The documentation for the Examples repo will be hosted at http://pigweed.dev, + but will be built from source within the ``examples.git`` repo. Building + documentation using :ref:`module-pw_docgen` is one of the things we're + exemplifying. + +* **Location**: https://pigweed.googlesource.com/pigweed/examples.git + +Showcase repositories +===================== +* **User journeys** these repositories serve: + + * "I want to see a cool project built using Pigweed." + * "I'm looking for a full-fledged demo of what Pigweed is capable of." + * "I'm looking for a Show HN submission." + * "I want to convince my team Pigweed is powerful enough for our use case." + * "I need proof that Pigweed is a better way to develop embedded projects." + * "I need proof that Pigweed is production-ready." + +* **Repository contents**: One repository per showcase project. These projects + are standalone, with documentation that explains what they do. They're not + necessarily easy to stand up yourself, and may require custom hardware that's + hard to source. :ref:`Kudzu ` and `Gonk + `_ are examples of showcase + projects. + +* **Locations**: Showcase projects can be hosted anywhere. Open-source projects + created by third parties and not hosted on https://pigweed.googlesource.com + can also be showcases. + + We will host a list of Showcase projects, with brief descriptions, at + https://pigweed.dev/showcase. + +.. _seed-0122-standard-board: + +Standard board +============== +Pigweed will select a "standard board" for use in our code samples. Today, the +de facto standard board is the STM32F429I-DISC1, but we expect to select a +different standard board in the near future. Standard board selection will be +discussed in a separate followup SEED. + +---- +FAQs +---- + +.. _seed-0122-existing-samples: + +How do existing code samples map to this scheme? +================================================ +* `example/echo `_ + will be renamed to become :ref:`seed-0122-quickstart` for Bazel. +* `sample_project + `_ will be + renamed and reorganized to become the :ref:`seed-0122-examples`. +* `Kudzu `_ and `Gonk + `_ are Showcase projects. + + +What about inline code samples in the documentation? +==================================================== +We will continue to provide inline code samples in the documentation, and later +in 2024 may prototype solutions for ensuring they compile and pass assertions. +But this is out of scope for this SEED. + +-------------- +Open questions +-------------- +A followup SEED will discuss the selection of the "standard board" for Pigweed +Quickstart and Examples repositories. + +The exact feature set of the MVC application demonstrated by the Quickstart +repos is the subject of `SEED-0106 +`_. diff --git a/seed/BUILD.gn b/seed/BUILD.gn index ede3a9a1f0..3c79bd0713 100644 --- a/seed/BUILD.gn +++ b/seed/BUILD.gn @@ -197,7 +197,7 @@ pw_seed("0121") { } pw_seed("0122") { - changelist = 187121 + sources = [ "0122-code-samples.rst" ] title = "Organize Pigweed code samples" status = "Open for Comments" author = "Ted Pudlik"