[SSSD] RFC: A template for design documents
Hi,
I created a proposed template for our design documents:
https://fedorahosted.org/sssd/wiki/PageTemplates/FeatureDesign
For your convenience, I'll also paste the full page text at the bottom
of the e-mail.
As you can probably notice, the template is very similar to design text
Sumit started some time ago and what we've been (informally) using for
some time already. With this template, you'll see a combo box that
allows you to select the template when starting a new page.
There are two differences in comparison to what we've been using --
there is a new section "Use cases" that would include some real world
example of how the change can be used. Also "Overview of the
solution" and "Implementation details" are separate sections -- I
understand not all features (especially internal-only and trivial) can
be split this way. Nonetheless, I think it's a nice division to make in
general.
I also took a look at the FreeIPA design pages:
http://www.freeipa.org/page/Feature_template
and they also include a section called "Test Plan". I personally don't
think there is too much value in having a separate test plan and how to
test, but I'm fine with discussing it if other developers feel
differently.
What do you think about the template? Do you agree?
The template text follows:
= Feature Name =
Related ticket(s):
* https://fedorahosted.org/sssd/ticket/XYZ
=== Problem statement ===
Short overview (up to a couple of sentences) of the change being
designed. Might include pointers to reference materials (such as MSDN
articles when designing an AD integration feature) or other information
required to understand what the change is about.
=== Use cases ===
Walk through one or more full examples of how the feature will be used. If
this is an internal change only (refactoring, perhaps), include a sentence
saying so.
=== Overview of the solution ===
Describe, without going too low into technical details, what changes need to
happen in SSSD during implementation of this feature. This section should
be understood by a person with understanding of how SSSD works internally
but doesn't have an in-depth understanding of the code. For example,
it's fine to say that we implement a new option `foo` with a default
value `bar`, but don't talk about how is `foo` processed internally and
which structure stores the value of `foo. In some cases (internal APIs,
refactoring, ...) this section might blend with the next one.
=== Implementation details ===
A more technical extension of the previous section. Might include low-level
details, such as C structures, function synopsis etc. In case of very
trivial features (e.g a new option), this section can be merged with the
previous one.
=== How To Test ===
This section should explain to a person with admin-level of SSSD
understanding how this change affects run time behaviour of SSSD and how
can an SSSD user test this change. If the feature is internal-only, please
list what areas of SSSD are affected so that testers know where to focus.
=== Authors ===
Give credit to authors of the design in this section.