The FOLIO Project has four primary communication channels and several secondary communication channels. Read about the philosophy of the FOLIO communication channels for more background.
The four 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 as Discuss topics, sometimes it will be as a position paper on the wiki. In all cases, decisions should be recorded on one of the four 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 Discuss topics. 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.
Discuss - Web Forum/Mailing List
FOLIO uses discuss.folio.org (an installation of the Discourse software) for messaging. 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. 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.
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
What to keep in mind when using the Wiki
The wiki uses the same account as issues.folio.org, but this is a different account from Discuss. You must set up your account on issues.folio.org, but then you can log into the wiki with this account.
Issues - Bugs and Tasks
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.
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 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 and Description fields. Use Comments for further detail.
Follow up in other fora for any lengthy discussion. Then summarise into further issue tracker comments. Provide links in both directions.
GitHub - Source Code
FOLIO uses Git repositories in github.org/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 (Discuss, Wiki, Issues, or GitHub) for publication and vetting to the wider FOLIO community.
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. Are you on multiple Slack teams? You can set up your Slack theme to match the FOLIO color scheme.
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 Discuss, Wiki, or Issues, as appropriate.
FOLIO uses a WebEx subscription for group conference calls that require document and screen sharing.
FOLIO Communication Channel Philosophy
Like similar open source projects of the same scale, we know we are going to need a variety of communication paths: channels where we are communicating in real-time -- like chat and conference calls and in-person meetings -- channels where we aren’t in real-time -- like mailing lists, blog posts and bug reports -- channels where we are physically located together in time and space, and channels where we are physically apart or separated by time. We also know that there are and will be people who are focused full-time on the FOLIO project, those that have other responsibilities but need to track what is going on in the project, and those that are curious and just tracking the overall progress and ideas in the project. We have also seen worldwide interest in FOLIO -- Europe, Middle East, North and South America. And with that comes its own set of challenges across time and languages. And finally, have a strong suspicion if not hope that the project will grow and evolve.
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, 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.”