> On 12 Nov 2014, at 17:02, Jakub Hrozek <[email protected]> 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. _______________________________________________ sssd-devel mailing list [email protected] https://lists.fedorahosted.org/mailman/listinfo/sssd-devel
