Best Practices
Simple and effective
Using Issues
An Issue List is a product focused compendium that converts many things to tasks. Github's tool is powerful yet simple, as well as naturally tied to your files. Consider it like a Kanban system for distributed knowledge work.
Motivators:
Ideas: It is a place to record ideas before you forget them, and discuss, refine, prioritize, and reject with documented rationale.
Concerns: Document anything you see in usage that is not as you expected.
Features: Identify each testable function as an issue.
Outcome:
Tasks: Any of the above can be reduced to work - described clearly enough to implement in a sitting 4-8 hours. Use the Issue document to outline a complex task, break into pieces, and document the expected effects.
Completed Work: When a task is fulfilled the completion is recorded by the commit and pull request.
Collaboration:
- Before coding anything, write an issue to explain the need for a change or start a discussion on one.
- Encourage comments by asking help from specific people with @githubhandle.
- Use Markdown to communicate effectively with headings, bullets, and numbering.
- Use pictures to explain, just paste them into the editor.
Automation and De-duplication
- When writing the issue or committing, use github's reference syntax in commit messages to refer to issues or other commits. i.e. (per #26, "Closes #30" , "Per 5dfa95")
- Use Reference syntax to obsolete older or less clear issues.
Managing
- Before working, review the fresh issues and convert to tasks where possible.
- Use Labels to categorize Issues that are Ready, or Nor Ready, Not Important
- Prioritize and Assign the "Ready" tasks periodically at the start of each sprint.