Developers need to efficiently discuss various topics such as issues, usage quirks, new features, and documentation improvements. Remember that other developers, the recipients of your messages, are also busy. They also operate in different time zones. In such busy projects, items can be easily overlooked, especially when in an inappropriate forum.

We each need to pause and consider the best forum. There are no rules, but these guidelines can assist.

As explained in the collaboration tools section, we have four primary fora: Discuss (messaging forum), Wiki (documents), Issues (bug and task tracking), and GitHub (source code and pull requests).

There are also secondary communication channels, including: Slack (realtime chat), WebEx (FOLIO Forum, conference calls), Twitter, and in-person meetings. If something important occurs in a secondary channel, it must be recorded in a primary channel.

We follow a variation of the Apache motto: If it didn’t happen in one of the primary communication channels (Discuss, Wiki, Issues, and GitHub), it didn’t happen.

General notes

  • See also other notes about FOLIO Communication Spaces.

  • 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.

  • Use well-chosen words for topic titles and introductory sections. This will make it easier to later list and search.

  • 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.

  • Try to search before starting a new topic. If there are duplicates, then link them.

  • Do not expect immediate answers.

  • Try to keep discussion focussed, and as close to the item 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 JIRA issue tracker.

Discuss

https://discuss.folio.org

  • For asking questions and recording discussions.

  • Use the relevant categories.

  • For topics that need lengthy or open-ended discussion, this is definitely the place.

  • If in doubt about which forum to commence a discussion, then using a Discuss topic is the best place.

  • You might be subsequently asked to explicitly add an Issue Tracker item. Link in both directions.

  • When seeking input from the broadest reach of FOLIO participants.

  • To post or comment, sign up for an account via the front page.

Wiki

https://wiki.folio.org

  • Position papers, meeting agendas and minutes, special-interest group (SIG) spaces, other guidelines.

  • To post or comment, sign up for an account via the front page (uses the same account as issues.folio.org).

Issue tracker

https://issues.folio.org

  • Specific bugs, problems, feature requests.

  • Also tasks that you know need to be done sometime later.

  • If not clear whether to add a new issue, then commence a Discuss topic first, and later summarize into an Issue.

  • Describe the issue concisely in the Summary and Description fields. Use Comments for further detail. See Guidelines for FOLIO issue tracker.

  • Follow up in other fora for any lengthy discussion. Then summarise into further issue tracker comments. Provide links in both directions.

  • To create issues or comment, sign up for an account via the front page.

GitHub

https://github.com/folio-org

  • 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, e.g. “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).

Slack

https://folio-project.slack.com (join here first).

  • Real-time chat and messaging.

  • Summarize topics out to other fora for better visibility. Remember that Slack is a secondary channel: significant ideas and decisions must be recorded elsewhere (Discuss, Wiki, Issues or GitHub) for broader vetting.

  • Follow up on missed topics. This can occur when a flurry happens about other topics. Also everyone is busy, and may intend to respond later. So pursue topics at a later time or venue.

  • A place to get together to solve a particular bug, or hold a brainstorming session, or to efficiently address a potential mis-understanding. Try to choose a time that suits people distributed around the world.

  • A place for heads-up type of notices.

  • Distinguish different Slack teams using Sidebar Themes: “FOLIO orange” and “FOLIO purple”.