Skip to content

Latest commit

 

History

History
146 lines (113 loc) · 5.46 KB

proposals.md

File metadata and controls

146 lines (113 loc) · 5.46 KB
Raw

Proposals

By default, standard contributors cannot commit directly to a locked branch, instead they must submit a proposal branch to be considered and voted on.

Permission to Propose

In order to make a proposal, a user must have at least the reputation points given by git config --user.<name>.scoreToPropose (See User Points).

Proposal Structure

Code

A PROPOSAL is a branch of a LOCKED BRANCH containing one or more consecutive commits, referenced with refs/heads/proposals/<id>, where <id> is the commit hash at the head of the PROPOSAL.

A PROPOSAL is said to be "OF branch <x>" if it is based on either:

  • A commit in the branch <x>
  • A commit in another PROPOSAL, which is itself of branch <x>
    • Note: It does not need to be the head commit

A proposal must be OF a LOCKED BRANCH.

DIAGRAM

Meta Data

The meta data for a PROPOSAL shall be stored in the tracking branch, under: .tracking/proposals/<id>/, where <id> is the commit hash at the head of the PROPOSAL. This directory is called the PROPOSAL DIRECTORY.

File names

There should always be one file within the PROPOSAL DIRECTORY named "proposal". Other file names are used for REVIEWS and are named after the reviewer:

filename := "proposal" / review
review   := <Addr-Spec as defined by RFC2822>

Proposal File

When creating a PROPOSAL, the PROPOSER should create a file named "proposal" in the PROPOSAL DIRECTORY.

Headers
Header Description
Proposer The name and email address of the proposer, as specified by RFC2822 (required)
Votes The numerical score of the number of WEIGHTED VOTES (required)
Status The status of the review. One of:
  • Open
  • Accepted
  • Rejected
(required)
Submitted-at The RFC2822 timestamp at the time of submmiting the proposal (required)
Extension-of Specifies the id of the PROPOSAL this extends (required when this proposal is an extension)
Extended-by This header may appear multiple times. It specifies the ID of a PROPOSAL which extends this proposal (required when extension proposals for this proposal exist)
Fix-of Specifies the id of the PROPOSAL this fixes (required when this proposal is a fix)
Alternative This header may appear multiple times. It specifies the ID of a PROPOSAL which fixes this proposal (required when fix proposals for this proposal exist)
Merged-By This header may appear multiple times. It specifies the ID of a PROPOSAL which merges this proposal into the LOCKED BRANCH (required when merge proposals for this proposal exist)
Merges Specifies the ID of a PROPOSAL which this PROPOSAL merges into the LOCKED BRANCH (required when this proposal is a merge proposal)

Submitting a Proposal

When submitting a PROPOSAL, a peer should:

  • Create the PROPOSAL DIRECTORY and fill the "proposal" file with their details, and the details of the proposal:
Proposer: Joe Bloggs <joe.blogs@example.net>
Submitted-at: Mon, 22 Feb 2015, 16:59:00 +0000
Votes: 0
Status: Open
[Extension-of: ID]
[Merge-of: ID]
[Fix-of: ID]

Text describing the proposal...
  • Update their USER FILE, incrementing the value of the Proposals Header by one.

Both these changes should be in a single commit on the .tracking branch, with the message:

Submitted Proposal: <id>

Types of Proposals

All new PROPOSALS are based directly on the LOCKED BRANCH, however when they are based instead on another PROPOSAL, they must be one of the following types:

Extensions

An EXTENSION is a PROPOSAL which is based on another PROPOSAL, and relies on features that it introduces. When an EXTENSION is APPROVED, it is not merged until all PROPOSALS below it are APPROVED.

As such, when a PROPOSAL is APPROVED, the client should also check if there are any APPROVED EXTENSIONS and MERGE them at the same time.

Fixes and Alternatives

A FIX is a PROPOSAL which modifies features that another PROPOSAL introduces. A FIX does not need to be based on the PROPOSAL which it fixes.

Approving a Fix

When a FIX is APPROVED, any other FIXES for the same PROPOSAL are automatically deemed to be REJECTED.

The FIX is based on the PROPOSAL it fixes

A PROPOSAL on which a FIX is based does not need to be APPROVED in order for a APPROVED FIX to be MERGED.

The FIX is not based on the PROPOSAL it fixes

A PROPOSAL on which a FIX is not based is automatically deemed to be REJECTED when the FIX is APPROVED.

Merges

When MERGING an APPROVED PROPOSAL results in a merge conflict, any user may attempt to solve the merge, and submit it as a new MERGE PROPOSAL.

A MERGE PROPOSAL must be a single commit, with the parents:

  • The head of the original PROPOSAL
  • The head of the LOCKED BRANCH OF the original PROPOSAL

When a MERGE PROPOSAL is APPROVED, any other MERGE PROPOSALS for the same PROPOSAL are automatically deemed to be REJECTED.