What is the best way to communicate new features or code?

[jbholden]

Is there a good way to document new features or code (planned or already implemented)?

• enter a new issue and label as enhancement?
• enter a new issue and label as question?
• create a new wiki page describing the feature?
• create a wiki page that lists all the latest changes?
• send an email?
• rely on the commit message when checking in code?

For example, I have been working on the following, where should it be documented?

• recently updated the Tests wiki page
• planning on creating a "visual tests" page (see Tests wiki page)
• created some test data in the /tests/data directory (see Tests wiki page)
• implemented the week results url page to show final results

[blreams]

Just thinking out loud...

I'm not a big fan of creating documentation work. If we use Issues to track new development, then the Issue itself becomes the documentation. For purposes of this discussion, Issue with a capital "I" refers to the github notion of Issue. IOW, there may be issues that need resolving in a new feature's Issue.

I think the wiki should only be used to document useability and implementation details. You wouldn't necessarily put something in the wiki for each new feature unless:

• You were describing the implementation details beyond what was in the Issue.
• You were describing how to use the new feature.

Back to Issues. Right now we have the default set of Issue Labels (enhancement, question, bug, duplicate, invalid, wontfix). But we can create others if need be. Issues can also be Assigned. Issues can also be added to a Milestone.

Because we are not a BIG distributed development team, we probably don't need to over-complicate this.

Let's start with the simple stuff. Either of us can create an Issue. But an Issue should not be assigned to one of us until we are actively working on development.

Issues are not limited to having a single Label. I think we should standardize on using the Enhancement Label to document new features. If there are questions or opens to be resolved, the Question Label should also be indicated. The following naturally falls out from this methodology:

• Issues labeled Enhancement, Question -- Indicates an open that must be answered before development can begin/proceed.
• Issues labeled Enhancement -- Indicates new development that can be tackled.

I've also seen where Labels can be used to indicate priority...not sure we need to go there yet.

I'm not really sure how to use Milestones, skipping over that for now.

Issues can be Open or Closed. It probably makes sense to change an Issue to Closed once development on the Issue is completed/committed.