From 40f966c99662ff322dcf871cbf5c85892a63680c Mon Sep 17 00:00:00 2001 From: Demetris Roumis Date: Mon, 15 Apr 2024 17:33:20 -0700 Subject: [PATCH] [HEP] HEP Purpose, Policy, and Guidelines (#395) * draft hep policy and align hep1 * broaden scope * reformat HEP 0 to align with proposed format * Apply suggestions from code review Co-authored-by: James A. Bednar * add md title to HEPs * add resolution section to HEP1 * make specification required * add compliance suggested section * elevate resolution section * minor wording update * status changed to accepted --------- Co-authored-by: James A. Bednar --- hep/accepted_heps.md | 6 +++ hep/hep0.md | 108 +++++++++++++++++++++++++++++++++++++++++++ hep/hep1.md | 45 ++++++++++++------ 3 files changed, 144 insertions(+), 15 deletions(-) create mode 100644 hep/accepted_heps.md create mode 100644 hep/hep0.md diff --git a/hep/accepted_heps.md b/hep/accepted_heps.md new file mode 100644 index 00000000..8fe28b49 --- /dev/null +++ b/hep/accepted_heps.md @@ -0,0 +1,6 @@ +## Accepted HEPs: + +| HEP | Title | +| --- | ------- | +| [0](hep0.md) | HEP Purpose, Policy, and Guidelines | +| [1](hep1.md) | Python version support | \ No newline at end of file diff --git a/hep/hep0.md b/hep/hep0.md new file mode 100644 index 00000000..ca713754 --- /dev/null +++ b/hep/hep0.md @@ -0,0 +1,108 @@ +# HEP 0 - HEP Purpose, Policy, and Guidelines + + + + + + + + + + +
Identifier HEP 0
Title HEP Purpose, Policy, and Guidelines
Status Accepted
Author(s) Demetris Roumis
Created March 18, 2024
Updated April 15, 2024
Discussion https://github.com/holoviz/holoviz/pull/395#issuecomment-2007702201
Implementation NA
+ +## Summary + +HEP 0 outlines the purpose, policy, and guidelines for future HEPs. This document aims to ensure that the process of proposing and implementing enhancements to the HoloViz ecosystem is clear, structured, and inclusive. + +### What is a HEP? + +A HEP is a HoloViz Enhancement Proposal, a design document requiring widespread attention and discussion that either proposes a specific change or else clarifies and codifies existing practice. These changes or codifications can be technical or address the social aspects of the organization, like governance or conduct. HEPs should provide a concise specification and rationale for the proposed change. HEPs serve as the principal means for proposing significant changes and formalizations for the HoloViz ecosystem, enabling the community to engage in informed decision-making while also documenting the proposals and the processes behind these decisions. + +HEPs are maintained as text files using Markdown for formatting in the [HoloViz/HoloViz](https://github.com/holoviz/holoviz) repository. Their revision history is a historical record of the proposed change. + +## Policy +### Core Developers +There are several references in this HEP to 'core developers'. This term refers to the currently active HoloViz core team members, collectively described by the combined MEMBERS.md files ([example](https://github.com/holoviz/holoviz/blob/main/doc/governance/project-docs/MEMBERS.md +)) in each of the HoloViz repositories. The core developers are reachable on HoloViz [GitHub](https://github.com/holoviz/holoviz) or [Discord](https://discord.gg/rb6gPXbdAr) with the handle: `@holoviz-dev`. + +### Steering Committee +There are several references in this HEP to the 'steering committee'. The currently active HoloViz steering committee is listed in [STEERING-COMMITTEE.md](https://github.com/holoviz/holoviz/blob/main/doc/governance/org-docs/STEERING-COMMITTEE.md), and is governed by [CHARTER.md](https://github.com/holoviz/holoviz/blob/main/doc/governance/org-docs/CHARTER.md). The steering committee members are reachable on HoloViz [GitHub](https://github.com/holoviz/holoviz) or [Discord](https://discord.gg/rb6gPXbdAr) with the handle: `@steering-committee`. + +### Workflow +#### Initiation +The HEP process begins with an idea for how HoloViz works or should work, whether that is a change from current practice or an explicit declaration of current practice. These enhancements can be technical or address the social aspects of the organization, such as governance or conduct. + +Before beginning to write a HEP, it is best to ascertain if the idea fits the intent of the HEP process and has a chance of acceptance. Informally vetting an idea publicly before going as far as writing a HEP is meant to save the potential proposer time. Small or uncontroversial changes often do not need a HEP and can be decided on in the [community channels](https://holoviz.org/community.html). Major or potentially controversial changes, such as those that require collaboration across multiple HoloViz projects, are expected to be submitted as HEPs. When it is unclear if an enhancement is suited for a HEP, ask HoloViz core developers to provide guidance. For example, the 'new-contributors' Discord channel is open to the public and a good place to ask. + +#### Drafting +Once the proposer has confirmed with the HoloViz core developers that an idea has any chance of acceptance, a draft HEP should be written following the format described below. Drafting can take place in a pull request to the HoloViz/HoloViz repository, but the status should be changed to 'draft' while working. + +HEPs should focus on a single issue; broad topics for discussion should be split into multiple well-focused HEPs. + +#### Submission and Consensus-Building +Once complete, the draft HEP should be submitted as a pull request to the HoloViz/HoloViz repository with the status changed to 'proposed'. At this point, all members of the HoloViz community are welcome and encouraged to participate in the review in a civil and respectful manner. + +The HEP proposer is responsible for following the discussion on the pull request, answering questions, making updates to the proposal as part of the consensus-building process, and documenting dissenting opinions. In general, the goal is to make sure that the community reaches consensus, not to provide a rigid policy for people to try to game. When in doubt, err on the side of asking for more feedback and looking for opportunities to compromise. + +When the proposer determines that the HEP is ready, they must notify the HoloViz core developers that it is ready for a formal review (e.g., in a comment on the pull request, using `@holoviz-dev`). This message must also describe any major points of contention and how they were resolved. + +#### Review and Resolution +A HoloViz core developer will then formally review the pull request for format, scope, and evidence of consensus. They may also notify other interested parties to weigh in on the HEP. If consensus has been reached, the HoloViz core developer will update the status of the pull request, assign a HEP number, add a link to the discussion in the [HEP table](accepted_heps.md), and merge it. All HEPs will be resolved as either 'rejected', 'accepted', or 'deferred' depending on the consensus of the community. + +In unusual and controversial cases where consensus has not been possible to achieve, a HoloViz core developer may ask the steering committee to take a HEP up for vote, following the policies described in [CHARTER.md](https://github.com/holoviz/holoviz/blob/main/doc/governance/org-docs/CHARTER.md). + +## HEP Format + + +### Title +All HEPs should begin with markdown title-level heading in the format of '# HEP {Identifier} - {Title}'. The identifier should remain a placeholder until a core developer has reviewed the pull request and assigned a number. The `Title` should match the entry in the table below. + +### Table +Next, each HEP should include a table with the following information: + + + + + + + + + + +
Identifier [Number to be assigned by HoloViz core developer upon HEP acceptance]
Title A short title of the proposal
Status Draft | Proposed | Accepted | Rejected | Deferred | Implemented | Superseded
Author(s) Full Name [email is optional]
Created March 15, 2024
Updated March 15, 2024
Discussion link to the issue where the HEP is being discussed, NA before submission
Implementation link to the PR for the implementation, NA if not available
+ +### Summary +A concise overview of the HEP's content. + +### Resolution (if applicable) +A concise summary of the technical plan of action. + +### Specification +If a HEP is perscriptive in nature (providing explicit guidelines or rules to follow), a **Specification** or **Policy** section is required to convey the technical details of the proposed enhancement. + +### Optional Sections +Some sections that may be +included if appropriate for the proposal include: + +- **Motivation/Background**: Why the proposed change or formalization is needed (beyond what is covered in the Summary). +- **Rationale**: Why particular decisions were made in the proposal. +- **Backwards Compatibility**: Will the proposed change break existing packages or workflows. +- **Alternatives**: Any alternatives considered during the design. +- **Sample Implementation/Illustration**: Links to prototype or a sample implementation of the proposed change. +- **FAQ**: Frequently asked questions (and answers to them). +- **Compliance**: Any mechanisms that promote adherence to HEP guidelines, favoring automation when possible. +- **Reference**: Any references used in the design of the HEP. + +### Copyright +A final **Copyright** section is required. + +## Pronunciation +HEP is to be pronounced `/hep/`. + +## Reference +A significant portion of this document was adapted from [CEP 1](https://github.com/conda-incubator/ceps/blob/main/cep-1.md) by the conda community. The [Numpy](https://numpy.org/neps/nep-0000.html) and [Python](https://peps.python.org/pep-0001/) versions of enhancement proposal guidelines were also referenced for inspiration. + +## Copyright +This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. + diff --git a/hep/hep1.md b/hep/hep1.md index 2ab5c9fb..2bb41aa7 100644 --- a/hep/hep1.md +++ b/hep/hep1.md @@ -1,8 +1,29 @@ -# HEP 1: Python version support +# HEP 1 - Python Version Support + + + + + + + + + + + +
Identifier HEP 1
Title Python Version Support
Status Accepted
Author(s) Ian Thomas
Created April 19, 2023
Accepted May 23, 2023
Last Updated March 15, 2024
Discussion https://github.com/holoviz/holoviz/pull/362
Implementation NA
+ + +> Note: HEP 1 was updated on March 15, 2024 by Demetris Roumis to align with the updated HEP format, proposed by HEP 0. Notably, he added the table above and the 'Resolution' section below. If there is any discrepency between the reformatted HEP 1 and the original HEP 1, the original HEP 1 takes precedence. + + +## Summary This enhancement proposal describes the possible policy that HoloViz projects -might adopt for support of Python versions. It is currently a discussion -document and has not yet been accepted. +might adopt for support of Python versions. + +## Resolution + +The community decided to adopt a Python version support policy for HoloViz projects that aims to support as many active Python releases as reasonably possible, with specific policies tailored for projects with few dependencies, those tightly coupled to Bokeh, and those with geospatial dependencies, ensuring alignment with dependent libraries' support cycles. ## Background @@ -38,7 +59,8 @@ will be released in October. NumPy's previous release (1.24.2) supported Python release (3.1.0) supported Python 3.8 to 3.11, and the next release (3.2.0) will support Python 3.9 to 3.11. -## Policy +## Specification/Policy + Ideally HoloViz projects should support as many Python releases as are reasonably possible. Support for a new Python release should ideally occur on @@ -77,7 +99,7 @@ For 3 the geospatial dependencies often cause problems by not being available as wheels on PyPI and being difficult to resolve on conda. The HoloViz policy should be the same as that of 2 above for uniformity. -## Illustration +## Illustration To illustrate the proposed policy, this is what it means for the remainder of 2023. @@ -94,14 +116,7 @@ release (3.2.0) will support minimum Python 3.9. All HoloViz projects (except Colorcet and Param which are covered above) should drop support for Python 3.7 as soon as possible to support a minimum Python of 3.8. Following release of Bokeh 3.2.0 there should be one further release per -HoloViz project that supports Python 3.8 and then the minimum Python version -for each should increase to 3.9. - -## Revisions - -Changes to this document shall be recorded below: +HoloViz project that supports Python. -| Date | Change | -| ---------- | ----------- | -| 2023-04-19 | First draft | -| 2023-05-23 | Accepted | +## Copyright +This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. \ No newline at end of file