Contributing

Introduction

As an open-source project, Readium welcomes contributions from everyone - individuals, corporations and non-profit organizations. The best way to get started with Readium is to read through the introductory materials on this site, subscribe to the Readium Slack, the mailing list and, of course, download source code and start playing.

An important note to bear in mind is that YOU are the Readium team. The Readium Foundation has no “dedicated team” and every piece of the different Readium projects is done by Readium contributors.

The Roles of Participants

Contributor

  • Contribution can be done in a variety of ways: submitting or reviewing pull requests, participating in the Readium Dev calls and in architectural discussions, writing technical documentation, etc.
  • Anyone is welcome to contribute to Readium projects.
  • No special rights are required, anyone can submit a pull request from a private fork or open issues to question the API or architecture.

Maintainer

  • Maintainers are contributors with write access on Readium repositories.
  • They are tasked with:
    • Reviewing and merging the contributed pull requests, in a timely manner.
    • Leading on architecture, design and tooling decisions. There should be at least two maintainers per repository, if possible.
    • To avoid stalling progress in case of absence, or being too dependent on a given person.
    • There’s no such thing as a lead maintainer, decisions are collaborative and documented.
  • Since the work of maintainers is usually more impacting, it can reside in branches directly in the official repositories. This will foster a quick feedback loop from other contributors.

Release Manager

  • There is only one release manager per repository.
  • The release manager is tasked with versioning and distributing the releases of Readium Mobile SDK, which includes:
    • Testing the current state of develop for distribution (e.g. it must work properly with package managers).
    • Merging the develop branch into master, and tagging the version.
  • Even though the release manager has the acting role, the versioning process is done collaboratively:
    1. The release manager opens a Release issue on GitHub with the current state and changelog.
    2. Contributors can review the issue and ask questions or suggest modifications in the changelog.
    3. Upon validation, the release manager can proceed and release a new version.
    4. A post on the Readium Website is then used to broadcast the new version with its changelog and important migration information.

Contributors grant to the Readium Foundation and to recipients of software distributed by the Foundation a perpetual, worldwide, non-exclusive, nocharge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense and distribute their contributions and such derivative works.

Before contributing, please sign and send to the Readium Foundation the Readium Individual Contributor License Agreement (ICLA).

How to Contribute

  • Contributing to Readium is best done following these steps:
    1. Open an issue on the relevant repositories to state a problem you want to fix.
      1. This will avoid getting a pull request rejected because it doesn’t fit the design goals.
      2. It will help gather opinions and information from other contributors.
      3. Best practices on using Git will be detailed asap.
    2. (Optionally) Bring the subject in the Readium Dev calls for further discussion, if there’s matter for debate.
    3. Create a fix in a private fork, based on the develop branch.
    4. Submit a pull request for review on the repository.
  • Nobody (including maintainers) has a grant to push/merge significant commits on develop and master without peer-review first, through a pull request.
    • Exception is made for minor contributions, such as fixing typos, cleaning files or an obvious bug fix.

Review of Pull Requests

  • Before being merged, all pull requests (including the ones from maintainers) must:
    • Be reviewed by at least one contributor from a different company than the author.
    • Be opened for review for at least 2 weeks (a very interested contributor can request postponing a review if (s)he’s not available in the review window).
    • (For significant ones) Be mentioned during a weekly Readium Dev call.
  • By default, the responsibility of reviewing pull requests falls back on maintainers.
    • They should at least respond quickly to show that external contribution is valued by our community.
  • Anybody willing to review a pull request (including maintainers) must start a review following GitHub’s instructions. If the review can’t be done in the first 2 weeks after the pull request was opened, then the reviewer must notify the author that the review needs to be postponed with a comment on the PR.
  • If nobody was willing to review a maintainer’s pull request after the review window, then it can be merged.
  • Upon merge and if relevant, an entry in the next change log must be added with a link to the pull request and, if necessary, migration information for reading apps.

Coding Style

  • To avoid heated debates about coding style in PRs, contributors must follow a style guide agreed upon beforehand. Selecting the style guide is done collaboratively, privileging best practices and most established standards for each platform.
  • Automated linters are used to enforce coding style.
  • Not observing the style guide is a valid reason to reject a pull request.

Architectural Decisions

  • Because of their deeply impacting nature, each architectural and API decision must be first discussed and agreed upon through an issue on either architecture, or in the appropriate repository for platform-specific concerns.
    • Readium Dev calls and Slack are not the place to take architectural decisions, but they can be used for debate or suggesting ideas.
  • Upon agreement, a Markdown documentation will be produced to explain the architecture or API, and the solution will be implemented. This document will usually be stored into the Architecture repository on Github.

In Case of Disagreement

  • In such a collaborative project, disagreement is bound to occur. If it can’t be solved through informal discussion, then we follow this process:
    1. An issue is opened on the appropriate repository.
    2. Each side is given the opportunity to write a synthesized solution to the problem, or a counter-argument.
    3. We should avoid debating or going back and forth in longer discussions. Readium Dev calls or Slack can be used for that.
    4. Each possibility will be summarized by each debater – with a link to the detailed comments – in the first comment, and tagged with a GitHub emoticon (only the emotionally neutral ones, so Hooray, Heart and Rocket).
    5. Other contributors will be asked to vote for a given solution using the matching emoticon.
    6. During one of the following Readium Dev call, a decision will be taken according to the votes, and then documented in the issue.

Usage of GitHub

Branches

  • master is used for stable, versioned releases.
  • develop contains the in-progress work and recently merged pull requests.
    • Contributors are encouraged to have a debug build using develop branches to give quick feedback on new features and API changes, before it becomes fixed in master.

Issues

  • Because we use them for communication and decision, we need to pay attention to the quality of GitHub issues.
    • New issues must be reviewed frequently, and appropriately answered to, sorted, tagged and attributed by the maintainers.
      • Answering is free for all, the rest is done by maintainers.
  • Issues must be self-descriptive and understandable by other contributors, they are not personal todo lists.

Project Communication

Slack

Readium developers are using Slack for real-time chats.

Plase ask an invite for accessing the Readium Slack, then select the channnels you’re interested in (including “general”, “r2-swift”, “r2-kotlin” etc.).

Mailing List

There is also a mailing list for the Readium projects, essentially used for sending notifications to all interested parties.

To join, simply send mail to Ric Wright, requesting access.

You can also visit the Google Readium mailing-list page, where you can also browse the archives and request access.

Weekly Meetings

The Readium Engineering meeting is held each Wednesdays at 16.30h UTC.

It is hosted on the EDRLab GoToMeeting, here.

Phone access is also available from a large set of countries: phone numbers are available on demand (they change from time to time).

Note!

  • Use your microphone and speakers (VoIP) - a headset is recommended.
  • Please mute your phone if you are not talking to minimize interference.

Face to Face Meetings

Once a year, we try to arrange a face-to-face meeting of the developers and contributors. These usually but not always coincide with Readium membership meetings and/or major eBook conferences like the Digital Publishing Summit.

Meeting Archives

The agenda and notes from all meetings are archived in the Readium Google Doc cloud space. You can access the archives here.