[SSSD] RFC: A template for design documents

Jakub Hrozek jhrozek at redhat.com
Tue Nov 18 23:27:26 UTC 2014


> On 12 Nov 2014, at 17:02, Jakub Hrozek <jhrozek at redhat.com> wrote:
> 
> 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.

Since only Martin had a comment about Configuration Changes, I went ahead and changed one of the design pages:
https://fedorahosted.org/sssd/wiki/DesignDocs/RestrictDomainsInPAM

I think this design page was a good candidate since the design was already close to the proposal and the feature is clear and non-trivial at the same time.

As you can see, the diff was fairly minimal:
https://fedorahosted.org/sssd/wiki/DesignDocs/RestrictDomainsInPAM?action=diff&version=9&old_version=8

If there is no opposition against the design document format, I'll change the other design pages written during the 1.12 cycle and request a review from the original authors.


More information about the sssd-devel mailing list