Skip to content

Latest commit

 

History

History
165 lines (132 loc) · 11.5 KB

phep-0001.md

File metadata and controls

165 lines (132 loc) · 11.5 KB
PhEP {
	#id: 0001,
	#type: #process,
	#title: 'PhEP Purpose and Guidelines',
	#status: #integrated,
	#authors: [ 'Esteban Lorenzano' ],
	#created: '2021-07-15'
}

Abstract

This PhEP describes the process to incorporate new features to the Pharo environment and its ecosystem.

Motivation

In order to improve the participation of the community in the development of Pharo, and allow better visibility of the general direction of the environment, we propose the adoption of a process to discuss and approve (or reject) important changes and features.
The introduction of a more formal system can be seen indeed as the introduction of some bureaucracy we didn't have before and for some probably unnecessary, but along with our perpetual search for community participation, visibility and predictability are also two necessary dimensions for the upcoming Pharo releases.
This proposal is largely inspired in python's PEPs and it will be taking most of the structure proposed, looking for simplification when the differences of size and culture of our communities allow it.

Description

What is a PhEP?

PhEP stands for Pharo Enhancement Proposal. A PhEP is a design document providing information to the Pharo community, describing a new feature for Pharo or its processes or environment. The PhEP should provide a concise technical specification of the feature, and a rationale for the feature. A reference implementation is not required at this stage. We intend PhEPs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into Pharo. The PhEP author is responsible for building consensus within the community, documenting dissenting opinions and providing the implementation.
Because the PhEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal.

PhEP Audience

The typical primary audience for PhEPs are the developers of the Pharo environment and its virtual machine as well as developers of parts of the "Pharo ecosystem" (the libraries/frameworks/tools not part directly of Pharo but that have an interest for it) .
The Pharo Board is also a privileged audience, since is its role to oversight and provide final approval or rejection of the proposals.

PhEP Types

There are four kinds of PhEP:

1, 2 and 3: "Image", "VM" or "Ecosystem" PhEPs are similar in objective: describes a new feature or implementation (or a removal!) for Pharo, but affects a different place of what is considered "Pharo": the "image" is what you can get in the "vanilla" image you download as Pharo, the "VM" are the proposals affecting the Pharo Virtual Machine and "Ecosystem" describe some feature that affect what is considered part of the Pharo Ecosystem (libraries, tools used to support developing with Pharo, etc.).

4: A "Process" PhEP describes a process surrounding Pharo, or proposes a change to (or an event in) a process. Process PhEPs are like standards PhEPs but apply to areas other than the Pharo environment itself. They may propose an implementation, but not to Pharo's codebase; they often require community consensus. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Pharo development.

PhEP Status

A PhEP can be in different status since its submission until it's implemented and put in production (see workflow below):

discussion: this PhEP has been submitted by its author and it's under revision and discussion by the board and the community. rejected: this PhEP has been rejected by the board or the community after discussion. See below Reasons to reject a PhEP. accepted: this PhEP has been accepted by the board or the community after discussion. The PhEP is not yet implemented or it is not integrated into the main Pharo repositories. implemented: this PhEP has been accepted and has an available implementation, not yet integrated into the main Pharo repositories. Potential testing and integration effort are required. It is possible to go directly from discussion to implemented if an implementation is available at the moment of the submission. integrated: this PhEP has been accepted, implemented and integrated into the main Pharo repositories. process PhEPs that do not require automation support can go directly from discussion to integrated.

PhEP Workflow

What is an enhancement for Pharo?

There are tons of things that can be done for Pharo, any idea of a new feature or a change for an already existing feature, but is important that the proposals stay on focus and do not expand besides its concrete objectives (Of course, small enhancements or bugfixes do not require a PhEP).
A PhEP requires an "author": someone who pushes the idea, provide an implementation and is responsible to make consensus around its idea. Discussing informally with the community before (in pharo-dev list or our discord server) can save time and give the author the chance of fleshing out its proposal, but is not a requirement.
In case of approval of the proposal, the author is also responsible of its implementation (made by him or ensured by him in some way).

Workflow summary for PhEP proposers

This is the workflow followed for PhEP proposers.

  1. (Optional, but recommended) the proposer discusses the idea in pharo-dev list or discord, with members of the team, and gather ideas.
  2. The proposal will clone the PhEP repository (pharo-project/pheps) and adds a proposal draft following the required stucture:
    • the file will not have an ID, hence it needs to be called phep-proposal.md
    • the proposal will have the header and structure explained in the section Submitting a PhEP (header, abstract, motivation and description).
    • the proposal will also have a "champion" (which by default is the author itself), responsible for the implementation of the proposal in case is been accepted.
  3. The proposal will be submitted as PR to the PhEP repository.
  4. A mail will be send to pharo-dev mailing list, including the link and the abstract of the proposal.
  5. There will be a discussion process and in case of acceptance of the proposal, an ID will be assigned by the reviewer.
  6. As final stage, the author renames the phep-proposal.md file as phep-ID.md and includes the ID in the phep file header (this step can be performed by the reviewer if he decides so).
  7. The reviewer will merge the PR

Workflow summary for PhEP reviewers

This is the workflow followed for PhEP reviewers (the members of the Pharo Board or its delegate).

  1. The reviewer checks the PR is correctly written and structured.
  2. The reviewer does "the first pass" verifying the proposal correctness.
  3. The submission of the proposal open a "discussion process", that will be held in the comments of the PR, and it will last until the reviewer accepts or reject it.
  4. If the reviewer considers the proposal needs to be accepted, this still counts as one (1) vote, and it needs to ask for the majority of the board to vote.
  5. When four (4) votes have been reached, the reviewer will assign an ID to the proposal.
  6. When the author submits the "final stage", the reviewer merges the PR.

Submitting a PhEP

The PhEP author is also responsible for the PhEP implementation, but if this is not the case, a responsible should be pointed when submitting a PhEP. Submitting a PhEP means

  1. submit a Pull Request to the pheps repository, with title and format described below.
  2. send an announcement of the PR (with teh abstract and link provided) to pharo-dev list, to make everybody interested aware of the new submission.

Pull request title The PR title has also a format to follow, to facilitate working with it:

[Type] Small description E.g: [Process] Guidelines to contribute to Pharo [Image] Move help browser contents outside the image [Ecosystem] Autogenerate a PhEPs website to allow better search

PhEP file name All pheps need to be named accordingly. But at the beginning a phep does not has a number (since the phep number is assigned when approved). The pre-approved phep proposal file name will be always: phep-proposal.md (it will be renamed as final step for approval).

PhEP file structure The phep file has different sections (explained in detail below):

  1. Header
  2. Abstract
  3. Motivation
  4. Description

Header

The header will be a structure with STON format enclosed in markdown code block (to enhance visibility):

PhEP {
	#id: 0,
	#type: #process,
	#title: 'PhEP Purpose and Guidelines',
	#status: #integrated,	
	#authors: [ 'Esteban Lorenzano' ], 
	#created: '2021-09-15',
	#replaces: nil
}
  • id: the number of the PhEP (it is zero for proposals, the right id will be assigned upon acceptance).
  • type: the type of the PhEP, it can be #process, #image, #vm, #ecosystem
  • title: the title of the PhEP
  • status: the status of this PhEP. It can be #discussion, #rejected, #accepted, #implemented, #integrated.
  • authors: the author of the PhEP, since there can be more than one, this field is an array.
  • created: the date of creation in yyyy-mm-dd format.
  • replaces: the id of the PhEPs this PhEP replaces (optional)
Header fields and types
  • #id: Integer.
  • #type: #process, #image, #vm or #ecosystem.
  • #title: String
  • #authors: Array of String.
  • #created: String with YYYY-MM-DD format
  • #replaces: Array of Integer.

Abstract

A brief introduction of what you is the goal of the PhEP.

Motivation

Reasons to make the change, adopt the new feature.

Description

A detailed description of the PhEP and its proposed design.

PhEP Review and Resolution

The Pharo Board is responsible of reviewing and resolve the PhEP proposal. They may take the job in their hands (the "regular" situation) or they may delegate it to someone else the Pharo Board considers is in condition of taking over the process for this particular PhEP (but notice that the final approval is exclusive responsibility of the Pharo Board, without possible delegation.
Before its resolution, a PhEP will be reviewed in several steps.

  1. it will be reviewed in style and consistence.
  2. a review on technical quality and feasibility will be demanded to the core team
  3. at all moment, the PR will be open for discussion with any member of the community (but again, acceptance or rejection is the job of the Pharo Board).
  4. If the PhEP is rejected, the PR will be closed and no more discussion will be held.
  5. If the PhEP is accepted, the Pharo Board (or its delegate) will assign an id to the proposal, the delegate will ask to rename the proposal file name and incorporate the id to the header, before squashing and merging the PR into main branch.
  6. Once integrated, the PhEP need to be be moved to integrated/pharo-version directory.

Reasons to reject a PhEP

There are plenty of reasons why a PhEP can be rejected, but just to point the obvious:

  1. The PhEP is not written clearly or it lacks focus.
  2. The PhEP is in contradiction with another idea being implemented (or already there).
  3. The PhEP does not fits with the Pharo vision and its goals.

PhEP Maintenance

It can happen that a PhEP replaces the feature or process described in another PhEP. In this case, several steps needs to be taken:

  1. the replaced PhEP(s) need to be moved to replaced/pharo-version.
  2. the replacing PhEP header need to incorporate the field replaces.