...
Decisions need to be recorded in an appropriate place. Sometimes that will be the Issue Tracker, sometimes it will be as a position paper on the wiki. In all cases, decisions should be recorded on one of the primary communication tools.
Use well-chosen words for topic titles and introductory sections. This will make it easier to later list and search topics.
Make links in each topic, e.g. between an issue tracker item and relevant documentation. Our future selves will be thankful when we need to explore the reasons for a certain change. Note that it is also possible to copy links from the Slack archive into
Try to search before starting a new topic. If there are duplicates, then link them.
Do not expect immediate answers.
Try to keep the discussion focused and as close to the source topic as possible. For example, if your feedback is about a certain GitHub commit, then use its comment-on-commit facility. Likewise with pull requests and issue.
| Anchor |
|---|
...
FOLIO uses discuss.folio.org (an installation of the Discourse software) for public discussion. The Discuss site is a web forum with categories, topics, and posts. You can interact with Discuss like a mailing list if that is your preferred mode. You can register yourself for an account on the Discuss site; see the "Sign up" link in the upper right corner of the page. Discuss also offers a getting started guide. When in doubt about which tool to use, use a Discuss topic as the way to start a discussion.
When to use Discuss
- Asking questions and recording discussions
- Recording important ideas or decisions made in a secondary communication tool (e.g. Slack, Skype, meetings)
- Seeking input from the broadest reach of FOLIO participants
What to keep in mind when using Discuss
- Discussion in this tool does not happen in real-time. FOLIO has participants all over the world, and at least a full day should pass before decisions are made based on Discuss topics.
- Assign the relevant category to the topic. When it doubt, leave it unassigned and community moderators will assign it to the appropriate category.
| Anchor | |||
|---|---|---|---|
|
FOLIO uses this wiki (an installation of the Confluence software) to store documents with some permanence. Each SIG has a space on the wiki, which can be found using the space directory.
...
FOLIO uses issues.folio.org (an installation of the JIRA software) to track software development activity, request new features, report bugs in the software, and track tasks that have interrelated parts. The Team vs module FOLIO Module/JIRA project-Team-PO-Dev Lead responsibility matrix lists the JIRA project for each module.
...
- Bug reports may come from other tools (for instance, a Discuss post or a dialog on Slack). Whenever possible, provide a link to the original source of the bug report.
- If it is not clear whether to add a new issue, create a topic on Discuss first and later summarize into an Issue. Provide links in both directions between the Discuss topic and the Issue.
- Describe the issue concisely in the Summary (Standard Bug Write-Up Format) and Description fields. Use Comments for further detail.
- Set the “Development Team” according to the wiki’s team vs module responsibility matrix so the Product Owner can triage and prioritize it.
- Additionally, if this is a bug that is affecting folks in production, set the “Epic Link” to SUP-12 and the SS will prioritize it.
Follow up in other fora for any lengthy discussion. Then summarise summarize into further issue tracker comments. Provide links in both directions.
...
With that in mind, we have set up four primary communication tools and acknowledge that there is a wide variety of secondary communication tools that will make sense for people to use as needed. The four primary tools are Discuss -- a web-forum and mailing list combination, the Wiki -- a document-centered tool, Issues -- an issue and task tracking system, and GitHub -- where the developers will keep track of code. Almost everyone involved with the project will use the first two tools -- Discuss and Wiki. Issues will become more widely used as FOLIO apps are created and tested, although there is quite a bit of activity on Issues already for the project as a whole and the platform code development. The primary tools were chosen because they address the challenges from the previous slide: they don’t depend on people working at the same time or in the same place, they have features that enable individuals to follow along on a topic when they have time, and they allow for multiple languages. We also know there are a variety of secondary tools, including a project Slack team, Skype, WebEx conference calls, and face-to-face meetings. These tools tend to be more immediate in nature, but that immediacy is also exclusionary because not everyone can participate. There is a motto that The Apache Software Foundation uses to tackle this problem. Apache is one of the oldest organizations supporting open source; it can trace its origins back to the development of some of the first web server code in the early 1990s. Apache also has many of the same characteristics that FOLIO has: worldwide interest, full-time and part-time contributors, and growing and evolving projects. Their motto is: “If it didn’t happen on a mailing list, it didn’t happen.” Or, put another way, if a conversation or decision didn’t happen in a forum with some permanence that everyone has access to, then it doesn’t count. We use a FOLIO variation on this motto: “If it didn’t happen on a primary communication tool -- Discuss, Wiki, Issues, or GitHub -- it didn’t happen.”
...