FOLIO Communication Spaces
The FOLIO Project has three primary communication channels and several secondary communication channels. Read about the philosophy of the FOLIO communication channels for more background.
The primary communication tools are:
Some general guidelines that apply to all tools:
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.
Wiki - Documents
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.
When to use the Wiki
Posting agendas and minutes from meetings
Publishing position papers describing proposed functionality
Documentation for resources such as the Roadmap
Marketing logos and branding documents
What to keep in mind when using the Wiki
Anyone is welcome to sign up for an account on the Wiki.
Issues - Bugs and Tasks
FOLIO uses the JIRA software to track software development activity, request new features, report bugs in the software, and track tasks that have interrelated parts. The FOLIO Module/JIRA project-Team-PO-Dev Lead responsibility matrix lists the JIRA project for each module.
When to use Issues
Recording software development tasks, assigning them to developers and tracking development progress
Recording software bugs and commentary on those bugs
Recording tasks that will need to be done at a later date and/or have dependencies on existing issues
What to keep in mind when using Issues
Bug reports may come from other tools (for instance, a dialog on Slack). Whenever possible, provide a link to the original source of the bug report.
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 Support SIG will prioritize it.
Follow up in other fora for any lengthy discussion. Then summarize into further issue tracker comments. Provide links in both directions.
See also
Getting Started for Product Owners - Manage you backlog in Jira
Release procedures: Jira Fix Versions Management Guideline, Release process in Jira
GitHub - Source Code
FOLIO uses Git repositories in github.com/folio-org to store the project's source code and to facilitate the integration of new code using GitHub's "Pull Request" functionality.
When to use GitHub
Downloading and building the FOLIO project from the source code.
Requesting new additions or changes to the code.
What to keep in mind when using GitHub
As explained in Guidelines for Contributing Code, use Feature Branches for any task beyond a minor text edit.
Use a descriptive name for the branch, with an Issue tracker number, if relevant. For instance: "folio-293-which-forum".
In the Pull Request, describe your main changes. Also say whether it is now ready to merge, or that you are seeking feedback.
To seek feedback on your work, use additional comments on your Pull Request. If the specific attention of certain people is needed, then @mention their names.
For specific comments on the work of other people, add comments to their Pull Requests or in direct response to their Commits (see example).
Secondary Communication Tools
There are a nearly infinite number of secondary communication channels; some of the most used ones are described here. Any significant idea, issue, or discussion that occurs in a secondary channel should be recorded in a primary channel (Wiki, Issues, or GitHub) for publication and vetting to the wider FOLIO community.
Mailing Lists
FOLIO uses mailing lists for internal communication in SIGs and committees. A directory of mailing lists is on the mailing list service homepage. The homepage also includes a form for subscribing to a mailing list and (for existing subscribers) receiving an email message with a link to manage mailing list options. (The "Account Login" button in the left sidebar of the homepage is for the mailing list administrator only.)
When to use Mailing Lists
To read broadcast announcements, join the folio-announce email list.
Communication between active members of SIGs and committees (for instance: canceling or rescheduling meetings)
What to keep in mind when using Mailing Lists
Mailing lists have limited visibility to the broader community. Most communication happens via Slack.
Slack
FOLIO uses a Slack team for real-time chat communication. You can request an account in the FOLIO team using the automated web form. (There is no review process for new account requests; the invitation is automatically sent to your email address.) Slack offers a getting started with Slack guide.
When to use Slack
Quick introduction or follow-up to new ideas
Fun banter between colleagues
What to keep in mind when using Slack
Not everyone is on all of the time. FOLIO participants work in many different time zones, and so you may not be reaching everyone with your conversation.
Slack can quickly become overwhelming. The daily commitment of FOLIO participants is a wide range, and significant points may be lost in a large scrollback buffer of text. Distill important points from Slack conversations into discussion posts (see Messages below).
Slack is not a place to record decisions. Slack's channel logs are the real-time thoughts of the participants (which can change over time). They are difficult to search for a particular point and even harder to summarize. Ideas and decisions should be recorded in the Wiki or Issues, as appropriate.