Page Comparison

Document your design

Anchor
DocumentYourDesign DocumentYourDesign

If you're working on a feature or a complex bug, document it in the space used for project designs on Confluence.  Put your design, called an External Design Document or EDD, in your design page.  Use the JIRA ID when you create your pageCreate a design document describing your design.  See this example.   Some bugs are small enough that they don't need documenting.  If you are not sure, ask on the development forum. 

Get comments on your design

Anchor
GetCommentsonYourDesign GetCommentsonYourDesign

Initiate a discussion of your idea or bug fix by starting a topic for it on the PBS Pro development forum:

• • Make sure you start your discussion in the Developers category in the forum
  • When you start your topic, prepend use a summary of the feature or bug for your topic title with the JIRA ID of your bug.  For example: PP-425: Server Periodic Hook
  • In the forum, add a pointer to your design page
  • If the feature is on the roadmap, mention that in your email

After you've started your topic, add an HTML link in your design page on Confluence that points to the discussion topic in the forum

Get review comments from community members about your bug fix or design.  Make sure review comments are solicited and posted in the development forum, and not on the wiki.  All discussion of your design and code should take place on the development forum.

Get approval for your design

Anchor
GetApprovalforYourDesign GetApprovalforYourDesign

For features or complex bugs, get sign-off of the high-level design approach from two people: one maintainer and one other contributor (who can be a maintainer).  If you took a complex feature and broke it down into sub-tasks, and you are working on a sub-task, you need two sign-offs on the design for your sub-task.  Make sure that all approvals are posted in the development forum, not on the wiki.

Make finding information easy

It's helpful to add links in the JIRA bug pointing to both Add a link in the design page containing the EDD and to the discussion, links in the design page containing the EDD that point to the JIRA bug and that points to the discussion, and of course links in the discussion to the JIRA bug and the design page.vice versa. 

Also add a link from the EDD to the pull request and vice versa.