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. _______________________________________________ sssd-devel mailing list sssd-devel@lists.fedorahosted.org https://lists.fedorahosted.org/mailman/listinfo/sssd-devel
