Skip to content

Latest commit

 

History

History
114 lines (93 loc) · 5.55 KB

libs_changes.md

File metadata and controls

114 lines (93 loc) · 5.55 KB
Raw

RFC guidelines - libraries sub-team

Motivation

  • RFCs are heavyweight:

    • RFCs generally take at minimum 2 weeks from posting to land. In practice it can be more on the order of months for particularly controversial changes.
    • RFCs are a lot of effort to write; especially for non-native speakers or for members of the community whose strengths are more technical than literary.
    • RFCs may involve pre-RFCs and several rewrites to accommodate feedback.
    • RFCs require a dedicated shepherd to herd the community and author towards consensus.
    • RFCs require review from a majority of the subteam, as well as an official vote.
    • RFCs can't be downgraded based on their complexity. Full process always applies. Easy RFCs may certainly land faster, though.
    • RFCs can be very abstract and hard to grok the consequences of (no implementation).

  • PRs are low overhead but potentially expensive nonetheless:

    • Easy PRs can get insta-merged by any rust-lang contributor.
    • Harder PRs can be easily escalated. You can ping subject-matter experts for second opinions. Ping the whole team!
    • Easier to grok the full consequences. Lots of tests and Crater to save the day.
    • PRs can be accepted optimistically with bors, buildbot, and the trains to guard us from major mistakes making it into stable. The size of the nightly community at this point in time can still mean major community breakage regardless of trains, however.
    • HOWEVER: Big PRs can be a lot of work to make only to have that work rejected for details that could have been hashed out first.

  • RFCs are only meaningful if a significant and diverse portion of the community actively participates in them. The official teams are not sufficiently diverse to establish meaningful community consensus by agreeing amongst themselves.

  • If there are tons of RFCs -- especially trivial ones -- people are less likely to engage with them. Official team members are super busy. Domain experts and industry professionals are super busy and have no responsibility to engage in RFCs. Since these are exactly the most important people to get involved in the RFC process, it is important that we be maximally friendly towards their needs.

Is an RFC required?

The overarching philosophy is: do whatever is easiest. If an RFC would be less work than an implementation, that's a good sign that an RFC is necessary. That said, if you anticipate controversy, you might want to short-circuit straight to an RFC. For instance new APIs almost certainly merit an RFC. Especially as std has become more conservative in favour of the much more agile cargoverse.

  • Submit a PR if the change is a:
    • Bugfix
    • Docfix
    • Obvious API hole patch, such as adding an API from one type to a symmetric type. e.g. Vec<T> -> Box<[T]> clearly motivates adding String -> Box<str>
    • Minor tweak to an unstable API (renaming, generalizing)
    • Implementing an "obvious" trait like Clone/Debug/etc
  • Submit an RFC if the change is a:
    • New API
    • Semantic Change to a stable API
    • Generalization of a stable API (e.g. how we added Pattern or Borrow)
    • Deprecation of a stable API
    • Nontrivial trait impl (because all trait impls are insta-stable)
  • Do the easier thing if uncertain. (choosing a path is not final)

Non-RFC process

  • A (non-RFC) PR is likely to be closed if clearly not acceptable:

    • Disproportionate breaking change (small inference breakage may be acceptable)
    • Unsound
    • Doesn't fit our general design philosophy around the problem
    • Better as a crate
    • Too marginal for std
    • Significant implementation problems

  • A PR may also be closed because an RFC is approriate.

  • A (non-RFC) PR may be merged as unstable. In this case, the feature should have a fresh feature gate and an associated tracking issue for stabilisation. Note that trait impls and docs are insta-stable and thus have no tracking issue. This may imply requiring a higher level of scrutiny for such changes.

However, an accepted RFC is not a rubber-stamp for merging an implementation PR. Nor must an implementation PR perfectly match the RFC text. Implementation details may merit deviations, though obviously they should be justified. The RFC may be amended if deviations are substantial, but are not generally necessary. RFCs should favour immutability. The RFC + Issue + PR should form a total explanation of the current implementation.

  • Once something has been merged as unstable, a shepherd should be assigned to promote and obtain feedback on the design.

  • Every time a release cycle ends, the libs teams assesses the current unstable APIs and selects some number of them for potential stabilization during the next cycle. These are announced for FCP at the beginning of the cycle, and (possibly) stabilized just before the beta is cut.

  • After the final comment period, an API should ideally take one of two paths:

    • Stabilize if the change is desired, and consensus is reached
    • Deprecate is the change is undesired, and consensus is reached
    • Extend the FCP is the change cannot meet consensus
      • If consensus still can't be reached, consider requiring a new RFC or just deprecating as "too controversial for std".

  • If any problems are found with a newly stabilized API during its beta period, strongly favour reverting stability in order to prevent stabilizing a bad API. Due to the speed of the trains, this is not a serious delay (~2-3 months if it's not a major problem).