At yesterday's community workshop, we discussed the fact that many new features
are being added to the framework and that existing APIs and syntaxes are
changing. We are concerned that our documentation will not be brought fully
up-to-date if we lose track of everything that's happening.
>From our discussion, a proposal arose for a way to keep track of these changes:
1) Every pull request must indicate whether documentation is required.
2) If so, the pull request should provide a very brief note of a) what the
change is and b) where more details can be found (e.g. a JIRA, specific tests,
an IRC chat, a mailing list post).
3) Pull requests will not be merged without this information.
4) When the code is merged, the reviewer will copy the documentation-related
information into a wiki page created specifically for this purpose.
Notes
-----
-- This process does NOT require that the developer issuing a pull request
write the documentation (although they're perfectly welcome to do so if they
want to!), merely that they provide pointers for the writer. An example might
be:
"We'll need to document the new 'fast invokers',
see FLUID-4922 and the tests on lines X-Y of Foo.js"
-- Requiring the reviewer to add the note to the wiki (rather than the original
developer) would ensure that the wiki page is only updated after the code has
been merged.
Obviously, we'd like to know the thoughts of the community on these changes,
since they affect everyone who issues pull requests and everyone who merges
pull requests – and everyone who uses our documentation. Do you have concerns
about this? Suggestions for improvement?
Please respond to this email with your thoughts.
--
Anastasia Cheetham Inclusive Design Research Centre
[email protected] Inclusive Design Institute
OCAD University
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
