Proposed refinement to pull request process

[Cheetham, Anastasia]

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
acheetham at ocadu.ca           Inclusive Design Institute
                                        OCAD University