Skip to end of banner
Go to start of banner

RFC Process

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 37 Next »

Introduction

Many changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal Jira-issue/GitHub-pull-request workflow.

Some changes though are "substantial", and we ask that these be put through a bit of a design process and produce a consensus among the Folio Technical Council.

The "RFC" (request for comments) process is intended to provide a consistent and controlled path for new features to enter the platform, and so that all stakeholders can be confident about the long-term and strategic direction for the platform.

When you need to follow this process

You need to follow this process if you intend to make "substantial" changes to Folio the platform, including but not limited to: Okapi, Stripes and Folio Core Modules, and Folio Architecture. What constitutes a "substantial" change is evolving based on community norms, but may include the following.

* Any changes to the Folio infrastructure including Okapi and Stripes
* The addition or removal of conventions, patterns and protocols that are key to the interoperability of Folio components.
* The removal of features that already part of a Folio release.
* Any change required for integration with systems external to Folio
* Changes that require the coordination between multiple Folio components or services.
* A new feature which might be considered redundant to existing features.

Some changes do not require an RFC:

* Rephrasing, reorganizing, refactoring
* Additions that strictly improve objective, numerical quality criteria (warning removal, speedup, better platform coverage, more parallelism, trap more errors, etc.)
* Changes that are scoped entirely to a single component or service of Folio
* Additions only likely to be noticed by other developers-of-Folio, invisible to users-of-Folio.

If you submit a pull request to implement a new feature without going through the RFC process, it may be closed with a polite request to submit an RFC first.

How to create a successful RFC

A hastily-proposed RFC can hurt its chances of acceptance. Low quality proposals, proposals for previously-rejected features, or those that don't fit into the near-term roadmap, may be quickly rejected, which can be demotivating for the unprepared contributor. Laying some groundwork ahead of the RFC can make the process smoother.

Although there is no single way to prepare for submitting an RFC, it is generally a good idea to pursue feedback from other project developers beforehand, to ascertain that the RFC may be desirable; having a consistent impact on the project requires concerted effort toward consensus-building.

The most common preparations for writing and submitting an RFC include talking the idea over on Folio Slack, if applicable presenting the proposal to the relevant SIG(s) and occasionally fully describing more complex concepts on the Folio Wiki.

As a rule of thumb, receiving encouraging feedback from long-standing project developers, and members of relevant SIGs is a good indication that the RFC is worth pursuing.

Process Overview

  • Review Phases

    • PRELIMINARY REVIEW (4 weeks Maximum. Can be extended by 1 week if approved)
      • RFC enters into the PRELIMINARY REVIEW stage once the submitter creates a PR in https://github.com/folio-org/rfcs
      • The submitter works with the TC to get feedback related to the overall scope and the general direction of the RFC.
      • The submitter will hold necessary discussions to resolve issues/concerns raised in the PR
      • The submitter will be responsible for resolving all the conversations in the PR
      • TC votes swiftly on whether there is any merit to the RFC
      • Any member of the TC will merge the PR in its current state to advance the PR to the next stage after ensuring that all conversations have been marked as resolved
      • RFC is likely to be rejected at this stage if there is a significant misalignment
    • DRAFT REVIEW(4 weeks Maximum. Can be extended by 1 week if approved)
      • Submitter creates a new PR for the DRAFT REVIEW stage
      • A subgroup is formed (must-have community/TC members who are experts in the area addressed by the RFC)
      • The subgroup works with the submitter to refine the RFC by providing feedback
      • The submitter will be responsible for resolving all the conversations in the PR
      • TC will review the draft when it is ready
      • Any member of the TC will merge the PR in its current state to advance the PR to the next stage after ensuring that all conversations have been marked as resolved
      • TC votes to advance the RFC to the next stage
    • PUBLIC REVIEW (3 weeks Maximum. Can be extended by 1 week if approved)
      • Submitter creates a new PR for the PUBLIC REVIEW stage

      • A message is sent to the public #tc-rfc slack channel announcing the PUBLIC REVIEW stage of the RFC

      • RFC opened up for a community-wide review. Anyone who wants to provide feedback can participate
      • Feedback is provided as PR review comments 

      • All Questions/Concerns/Suggestions provided as part of the public review feedback will be addressed. The submitter of the RFC will take the responsibility of facilitating discussions to address the comments provided

      • Anything that suggests a change in scope is likely to be NOT considered

      • The community should really take this opportunity to weigh in on the changes
      • Create POCs/RI's to identify any gaps (Optional)
      • Any member of the TC will merge the PR in its current state to advance the PR to the next stage after ensuring that all conversations have been marked as resolved
      • TC votes to advance the RFC to the next stage
    • FINAL REVIEW (2 weeks Maximum. Can be extended by 1 week if approved)
      • TC will review and deliberate over the comments from the community and decide what should be included and what should be left out of the RFC 
      • Submitter prepares the final version of the RFC
      • TC does the final review and Signs Off
      • TC should really work towards getting a consensus on this final vote or at least have an overwhelming majority in favor of the RFC

  • Post Review 

    • To help us learn, a retrospective will be performed regardless of the outcome of the RFC.

General Guidelines

  • Dedicated time slot for RFC review (Once every 2 weeks, as needed)
  • When submitting new RFCs, it is highly recommended to have a smaller scope. In case of a large scale change, consider breaking up the RFCs into smaller RFCs. This greatly helps the RFC get through the review process quickly.
  • When there are exceptional cases that results in a stalemate (when there is no clear path even after extension period for a given review phase), the TC will force a vote to decide on the fate of RFC. TC could negotiate with the stakeholders and strike compromise to keep the RFC moving forward or it could end up rejecting the RFC citing an appropriate reason
  • Feedback from anyone interested MUST be taken into consideration by the submitter at any stage during the review process as long as it is appropriately documented in the PR 

Resources

To Do's

  • Create new Slack Channel
  • Permissions in the RFC needs to be modified to allow users to resolve, create PRs
  • Add CODEOWNERS file that includes all members of the TC. We have TC group in Github


  • No labels