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, download the source code and start developing applications.

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. Contributors have therefore an important role in the organization.

Many developers take Readium toolkits and integrate them into their application without contributing back to the Readium project. This is fine, as the increase of the number of applications based on Readium toolkits mechanically improves the level of interoperability of EPUB 3 and Audiobooks reading systems. Non-contributing developers are considered “implementers” by the active Readium community and also have a role, plus some duties, detailed below.

The Roles and duties of Participants

Implementer

On Readium Mobile

If you decide to start a development based on Readium Mobile, please:

• Make sure that the whole dev team has a good understanding of Swift or Kotlin development depending the project you are involved in, including build systems, dependency management etc., i.e basics that are not part of the Readium codebase. The Readium community cannot help beginners.
• Before expecting help in solving your implementation issues, check the codebase of the TestApp provided with the Swift and Kotlin toolkit.
• If you have problems with the TestApp you just built, download the pre-compiled TestApp (links are found in the readme of the Swift and Kotlin toolkits).
• Once you have the TestApp running (and working with LCP in test mode if you are using it), this will hopefully leave only very specific questions to ask.
• If you have specific questions about the Swift or Kotlin toolkit and the answer is not found in the codebase, look first into Github discussions and issues.
• Readium Foundation members have an additional access to the Readium Slack, in the channels named #swift-toolkit and #kotlin-toolkit.
• If after careful testing you think you have discovered an issue in a toolkit, please open a Github issue in the proper repository.
• If the community cannot answer to your questions or help solving your problems, paid consulting should be considered.

On Readium Desktop

If you decide to start a development based on Readium Desktop (or EDRLab’s Thorium Reader), please:

• Make sure that the whole dev team has a very good understanding of Electron.js, Node.js, React.js and typescript, including build systems, dependency management etc. This project is not for faint hearts ;-).
• Other rules are the same as for the Readium Mobile toolkit.
• Readium Foundation members have an additional access to the Readium Slack, channel #desktop-toolkit.
• Application-level issues should be open in the EDRLab thorium-reader Github repository.

On Readium LCP

• Make sure that the whole dev team has a very good understanding of security on the Web (setting up https, securing confidential information etc.).
• Once you have obtained the test LCP client library from EDRLab, the instructions available in the toolkit should be enough to integrate the library without hiccup.
• If you have specific questions about the LCP Service and the answer is not found in the codebase, look first into Github discussions and issues.
• Readium Foundation members have an additional access to the Readium Slack, channel #lcp.
• Additional support is offered by EDRLab for LCP prospects.
• If the community cannot answer to your questions or help solving your problems, paid consulting should be considered.

Once the app is ready

• Please announce this achievement on Twitter/X or LinkedIn with a #readium hash tag, with links to the apps on the Apple and Google stores. We will then add your app to the “awesome Readium” page.
• The Readium community will appreciate if you promote Readium on social networks.
• It is still time to become a Contributor, see below …

Contributor

• Contribution can be achieved 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.
• Active contributors gain access to the Readium Slack.

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.

Grant of Copyright License

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

Contributions

How to Contribute

• Contributing to Readium is best done following these steps:
  1. Check previous issues (open or closed) and Github discussions. You may find that your problem is already treated.
  2. 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.
  3. (Optionally) Bring the subject in the Readium Dev calls for further discussion, if there’s matter for debate.
  4. Create a fix in a private fork, based on the develop branch.
  5. 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

Github issues are the prime medium for communicating about the evolution of the codebase.

Github discussions

Most Readium repositories have discussions attached, and they should be used in priority if you have a question. The core contributors are actively participating to these discussions.

Slack

Readium maintainers, active contributors and members are using the Readium Slack for real-time chats.

Weekly Meetings

A Readium Developer meeting is held every other Wednesday at a time compatible with Europe and US work hours. It is hosted on Zoom and notified on the Readium Slack (#general channel, 15 mn before each call).

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 Readium Foundation members and contributors. These usually but not always coincide with major eBook events like the FRankfurt Book Fair or the EDRLab Digital Publishing Summit.