Versions Compared

Old Version 37

changes.mady.by.user Jenn Colt

Saved on

compared with

New Version Current

changes.mady.by.user Craig McNally

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

...

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

...

Status
titlePreliminary Review

...

Process Overview

The RFC process is comprised of several stages which happen in sequence.  The purpose, steps, and advancement criteria for each stage is detailed below.

ABSTRACT PREPARATION  

Purpose:  The submitter prepares the RFC abstract and brings it to the attention of the Technical Council.

Timebox:  Approximately 16-17 weeks when incorporating review windows and accounting for administrative overhead, making adjustments, etc.

Steps:

  1. The submitter creates a PR in https://github.com/folio-org/rfcs but only populates the following sections:
    1. Metadata - Contributors, links to PRs, outcome, etc.
    2. Overview - An overview of what the RFC is about
    3. Scope - Defines the scope of what the RFC intends to cover/not cover
    4. Timing - Indicates a rough timeline of when the RFC might be ready
  2. The submitter updates the "RFC PRs" section of the metadata to link to the PRELIMINARY REVIEW pull request.
  3. The submitter should contact one of the Technical Council chairs and plan to attend a TC meeting in the near future to present the RFC Abstract.

Advancement Criteria:

  • A Pull request exists in https://github.com/folio-org/rfcs containing only the applicable sections.
  • RFC metadata contains a link to the RFC PR
  • The submitter has contacted a Technical Council chair and has scheduled a TC meeting in which the RFC Abstract will be presented and discussed.

NOTE:  If applicable, abstracts for closely related RFCs should be presented together at The Technical Council.  This would give The Technical Council insight into how a larger topic is being split up into smaller more digestible, related RFCs.  It will provide an opportunity to discuss the expected timing and sequence of RFC submissions.

PRELIMINARY REVIEW

Purpose:  Discuss and agree to the scope and general direction of the RFC.  The intent is to have a conversation between The Technical Council and the submitter, adjusting the RFC direction and scope as needed, prior to investing time in writing the full RFC.

Timebox:  ~ 2 weeks

Steps:

  1. The PRELIMINARY REVIEW stage begins once the submitter presents an RFC Abstract at a Technical Council meeting. 
    1. The presentation should be brief (~5 minutes max) and focus solely on the general direction and scope. 
    2. It's the responsibility of the meeting convener to ensure the presentation and subsequent discussion remains on topic and doesn't delve into details.
  2. One week will be given for TC members to consider the scope and general direction
    1. During this time, TC members are encouraged to provide feedback/questions relating to the scope/general direction of the RFC in the PR
    2. There shouldn't be feedback on details of the RFC at this stage.
  3. If necessary, the submitter may organize ad-hoc meetings/conversations to resolve issues/concerns raised in the PR
  4. The submitter will be responsible for resolving all the conversations in the PR

...

  1. At The Technical Council meeting following the RFC Abstract presentation, The Technical Council will vote swiftly on whether there is any merit to the RFC.

      ...

        1. If the submitter requires more time to make necessary adjustments, they should inform a Technical Council chair, and The Technical Council vote will be rescheduled.
      2. If approved, all conversations must be resolved and the submitter closes (Do not merge!) the PR in its current state

      ...

      2. Rejection is unlikely at this stage unless The Technical Council and submitter reach an impasse.  
        1. If rejected, the RFC metadata is updated to indicate this (Outcome: Rejected) and the submitter merges the PR.  Some conversations may remain unresolved in this case.

      Advancement Criteria:

      • All conversations have been marked as resolved
      • The PRELIMINARY REVIEW pull request has been closed (Not merged!)
      • RFC is likely to be rejected at this stage if there is a significant misalignment
      • Status
        colourYellow
        titleDraft 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
        • Status
        colourBlue
        titlePublic Review
         (3 weeks Maximum. Can be extended by 1 week if approved)        Submitter
      • The Technical Council has voted to proceed

      RFC PREPARATION

      Purpose:  Submitter and other contributors flesh out the rest of the RFC and notifies the Technical Council when it's ready for public review.  Submitters are encouraged to reach out to the TC and/or other community stakeholders during this stage as needed to get feedback on certain aspects of the RFC which may be controversial or confusing.

      Timebox:  ~ 1 month may be a good starting point, but if deviating significantly from the timeline indicated in the RFC Abstract, The Technical Council should be notified.

      Steps:

      1. The submitter works on the content of the RFC, staying true to the general direction and agreed upon scope.
      2. The submitter creates a new PR for the PUBLIC REVIEW stage
      3. The submitter updates the "RFC PRs" section of the metadata to link to the PUBLIC REVIEW pull request.
      4. The submitter contacts one of the Technical Council chairs when the RFC is ready for PUBLIC REVIEW.

      Advancement Criteria:

      • A new pull request exists for the PUBLIC REVIEW stage
      • RFC metadata contains a link to the new PR
      • The submitter has contacted a Technical Council chair indicating that the RFC is ready for PUBLIC REVIEW.

      PUBLIC REVIEW

      Purpose: Gather feedback from and discuss with any/all FOLIO community members

      Timebox:  ~ 1 month may be a good starting point. TODO: think about the periodic reminders indicating how much time remains in the feedback window.

      Steps:

      1. The submitter creates a new PR for the PUBLIC REVIEW stage
      2. The submitter updates the "RFC PRs" section of the metadata to link to the PUBLIC REVIEW pull request.

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

      4. The Technical Council and submitter determine if additional announcements should be made in other channels (e.g. #sys-ops, #folio-product-council, #development, etc.)
      5. RFC is opened up for a community-wide review. Anyone

      ...

      1. who wants to provide feedback can participate
      2. Feedback is provided as PR review comments 

      3. All

      ...

      1. questions/

      ...

      1. concerns/

      ...

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

      ...

      1. There will be a bias towards not changing the scope of the RFC at this stage as it would likely be disruptive. 

      2. The community should really take this opportunity to weigh in on the changes

      ...

      1. POCs/

      ...

      1. Reference implementations are developed to identify any gaps or unforeseen challenges (Optional)

      ...

      2. The submitter and Technical Council are in contact throughout this stage and together determine when the public review stage should conclude
      3. A message is sent to the public #tc-rfc slack channel announcing the PUBLIC REVIEW stage of the RFC has concluded.
      4. The submitter closes (Do not merge!) the PR in its current state to advance the

      ...

      1. RFC to the next stage after ensuring that all conversations have been marked as resolved

      ...

      Advancement Criteria:

      • All conversations have been marked as resolved
      • The PUBLIC REVIEW pull request has been closed
      • The Technical Council and submitter have together agreed that the RFC is ready for final review.

      FINAL REVIEW

      Purpose: Final review and discussion by Technical Council, leading to a decision

      Timebox:  This may not be needed. This stage seems to move quickly. If consistency is desired, a short duration (e.g., 1 week) could be chosen.

      Steps:

      1. The Technical Council will review and deliberate over the comments from

      ...

      1. the community 
      2. The submitter creates a new PR for the FINAL REVIEW stage
      3. The Technical Council does the final review and votes on whether the RFC should be Accepted or Rejected
      4. The FINAL REVIEW pull request is updated with appropriate outcome.
      5. A message is sent to the public #tc-rfc slack channel announcing the outcome of the RFC.
      6. The Technical Council should really work towards getting a consensus on this final vote or at least have an overwhelming majority in favor of the RFC

      ...

      Advancement Criteria:

      • The Technical Council has decided to Accept or Reject the RFC
      • The RFC metadata has been updated to indicate the outcome
      • An announcement has been made in the #tc-rfc slack channel indicating the outcome of the RFC
      • The FINAL REVEIW is merged

      POST REVIEW

      • To help us learn, a retrospective will be performed regardless of the outcome of the RFC.  
      • N.B. A formal decision should be logged in the Technical Council's Decision Log.  This is one of the primary deliverables of this process and should not be overlooked.  
        • If needed, the Technical Council can help the submitter with this.
        • Adding a list of keywords to the bottom of the DR would make it easier to find information via search.

      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 The Technical Council 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 
      • RFCs should be technically focused.  However, RFC feedback is not limited to technical questions and concerns.  It is both expected and acceptable for non-technical aspects to be raised and discussed throughout the RFC process.

      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