Skip FOLIO Project Navigation

GitHub and Twitter:

Which forum to use for communication

Introduction

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 three primary forums: Wiki (documents), Issues (bug and task tracking), and GitHub (source code and pull requests).

There are also secondary communication channels, including: Slack (realtime chat), FOLIO Forums, conference calls, Twitter @folio_lsp, 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 (Issues, Wiki, 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 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 GitHub events. 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.

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 Issue tracker front page. (The Wiki uses the same account as issues.folio.org and reset password happens there too.)

  • Assistance with Wiki search.

Issue tracker

https://issues.folio.org

  • Specific bugs, problems, feature requests, obscure messages or behaviour.

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

  • If not clear whether to add a new issue, then ask via Slack, 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 for notes about what to report and how to do so.

  • Follow up in other forums 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.

  • Assistance with Jira search.

GitHub

https://github.com/folio-org

  • See the lists of all repositories with sections for server-side and client-side and other projects.

  • As explained in Guidelines for Contributing Code, use Feature Branches for any task.

  • 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. Follow the guidelines Development, design, and review processes.

  • Ensure that the PR title refers to the relevant Jira ticket identifiers as explained in the requirements of Pull requests checklists and in the Guidelines for FOLIO issue tracker.

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

  • Use some identifying avatar or photo, indicate your timezone, and enhance your profile notes. In such a busy project this assists knowing a little about each other and enables the chat to be more easily followed.

  • Summarize topics out to other forums for better visibility. Remember that Slack is a secondary channel: significant ideas and decisions must be recorded elsewhere (Issues, Wiki, 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.

  • There are now many channels. Browse the list via the Slack application, to review and join any appropriate ones. Some are not public, so you will need to be invited. Some relevant channels for developers are:
    • #support – Any topic needing assistance.
    • #general – Community-wide general stuff. Use other channels for development topics.
    • #development – The main development area.
    • #releases – Discussion of quarterly release preparation, and announcement of regular module releases.
    • #pull-requests – A place to request reviews on pull requests.
    • #hosted-reference-envs – Issues with the reference environments automated builds.
    • #raml-module-builder – Specific discussion for RMB development.
    • #stripes – Specific discussion for front-end development.
    • #devops – Assistance with FOLIO infrastructure, requests to add new GitHub Team members, etc.
    • rancher-support (was previously known as #scratch-environments) – Assistance with the team-specific Rancher developer scratch environments.
    • #folio-ci – Notifications from the Jenkins CI. See usage notes. Mute this channel and visit when needed.

  • Use @mentions with care. This is especially important on broad channels such as #general, as using @channel there will send notifications to many hundreds of people.

  • Distinguish different Slack workspaces using Sidebar Themes: “FOLIO orange” or “FOLIO purple”.