develooper Front page | perl.perl5.porters | Postings from February 2021

how to get an idea to a merged PR

Thread Next
From:
Neil Bowers via perl5-porters
Date:
February 15, 2021 20:11
Subject:
how to get an idea to a merged PR
Message ID:
eda73eb4-41de-4731-ab86-1beeea21740a@Spark
Rik, Sawyer, and I have been discussing the process for how an idea can end up as a pull request. We’ve converged to the lifecycle outlined below, which we think is ready for feedback here.

Neil


From Idea to Merged PR

This document describes how ideas can end up as a merged PR for Perl. We expect that having it written down in one place will flush out funny edge cases, and prompt discussion on refinement.

Lifecycle

Here's the lifecycle, which is discussed in more detail below:

    https://i.imgur.com/KO73fhh.png

For trivial changes (typos in documentation, straightforward bug fixes), we'd expect people to go straight to a github pull request (PR). Otherwise you'll be expected to follow the process described below.

Summary

 * Send an email to p5p outlining your idea.
 * Your idea may be Rejected, or p5p might suggest it would (initially) be better as a CPAN module.
 * Otherwise, write a concrete proposal as a markdown file, and submit a PR adding this to proposals/.
 * If not vetoed by a subject-matter expert, and there wasn't unanimous agreement on p5p, PSC will rule on it.
 * Eventually that will hopefully result in a separate implementation PR.
 * The committers will discuss it, and decide whether it should be merged, with PSC resolving logjams.


Idea

There are two ways to submit an idea: (1) email to P5P, and (2) open a github issue. We suggest that bugs continue as issues, unless the fix is particularly gnarly (e.g. "no dot in @INC"). For changes to the language, please start off with an email to p5p: it's the public forum – not everyone is going to see all github issues raised.

Following discussion, there might be consensus that a CPAN module is the right way to address the need (see "CPAN" below). Or the idea may be rejected, for example because it's not feasible, it doesn't fit the language, etc.

There may be several alternatives, which will hopefully converge through discussion.


Proposal

If the idea isn't rejected, nor kicked off to CPAN, then it should result in a concrete proposal. This should be submitted as a PR that adds a markdown (.md) file in the proposals directory of the perl repo on github. The proposal should include an appropriate level of detail.

Now there's a very specific thing to discuss, and people might identify problems at this stage that weren't evident with a more vague idea. The proposal may be further refined. Discussion of the proposal should continue on the PR.

Part of this discussion should include whether a feature guard is needed, concerns on CPAN breakage, etc.

This is the point where a subject-matter expert may raise concerns about the proposal, and may effectively veto it. For example, if you propose a change related to Unicode, and Karl says "it's a really bad idea for the following reasons", then it's not likely to progress. Similarly, as the discussion progresses, it may become clear to everyone that it should be rejected.

Clarifying the idea might make people realise it should be a module on CPAN after all. Conversely, an idea that was kicked off to CPAN may end up coming back from CPAN as a proposed change to the language. e.g. try/catch and Moose/Moo leading to Cor.

Once a proposal has been submitted, we will ensure that it gets resolved one way or another. The PSC may ask (specific) people to comment, and specify a deadline.


CPAN

Some ideas might be met with "that could be done as a module". That might be because it doesn't belong in the language, or because people aren't sure on one or more aspects, so they want it to be experimented with.

Some ideas won't be worth having as a module, but are worth considering for a change in the language. E.g. indented heredocs.

Conversely, sometimes we might want to say something shouldn't be first done on CPAN, as once the syntax is in a module on CPAN, it's harder to introduce that syntax into the language itself.


Agreed

Following discussion of a concrete proposal, if it hasn't been vetoed, a decision is needed.

If we're lucky, everyone agrees that it's a good idea, and no ruling is required.

Otherwise, following appropriate discussion, the PSC will make a ruling, which will be one of: Rejected, Agreed, or Needs More Work. Being Agreed doesn't guarantee that a subsequent implementation PR will be merged. The document will be updated to reflect this.

Until someone decides to implement it though, it could sit in a pot of "agreed in principle, but no-one's implementing it". It would be good to have a backlog of agreed items, so people can look for things to do.


Implementation PR

One or more people will hopefully then work on the change, and eventually submit a PR.

There is an ongoing discussion how how we decide whether to merge a PR, with the latest proposal being:

 * After an appropriate period, if there are not strong disagreements, and the PSC haven't rejected it, a committer will merge the PR.
 * Trivial or obviously-correct changes may be committed directly. I.e., the appropriate length is sometimes zero.
 * If objections are raised, they need to be addressed (meaning "clearly replied to")
 * If the objection is from a subject matter expert, you need to come to an agreement.
 * If the PR stalls, ping the PSC for adjudication.
    (We expect this will be quite rare – either you should have gone through the proposal process, or it's straightforward).
 * PRs from non-committers are expected to have more scrutiny.

What's an appropriate period?

 * For "I think this is right but want to give a chance for comments", a couple days is probably fine.
 * For "this is a significant change that I could really use feedback on," a week or more is probably best,
    and the PR should probably be flagged to the list as wanting attention.
 * The later in the release cycle, the stricter we should be with ourselves.

Don't panic: changes can be reverted.


Roadmap

This gives us a mechanism for documenting features we'd like to add to Perl. Over time the "Roadmap for Perl" will be the set of Proposals that haven't been rejected.

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About