[HEP] HEP Purpose, Policy, and Guidelines

[droumis]

This PR introduces HEP 0, which outlines the purpose, policy, and guidelines for future HEPs within the HoloViz ecosystem. This document aims to clarify the process of proposing, discussing, and implementing enhancements for HoloViz evolution.

I've also updated HEP 1 to align with the format proposed by HEP 0.

[maximlt]

Thanks for putting this together!

The document says a HEP proposes a major change to the HoloViz ecosystem. I think that's a bit of a strong statement. For example, I don't consider HEP 1 has brought any major changes, and I don't think HEP 2 I'm working on is going to change HoloViz significantly. The scope of NEPs for example is a bit more laxed with a NEP being a design document providing information to the NumPy community, or describing a new feature for NumPy or its processes or environment. I'd suggest widening the scope of HEPs to something similar to NEPs.

Other than that, it looks good to me.

[droumis]

I'd suggest widening the scope of HEPs to something similar to NEPs.

I've adjusted the language to broaden the scope, please check if this is sufficient.

[maximlt]

Yes, thanks!

[maximlt]

Ah maybe another thing, perhaps the HEP should be formatted like it's saying HEPs should be, i.e. with the table and a summary?

[droumis]

updated to align with proposed format

[maximlt]

Thanks!

I think ultimately it'd be good to have the HEPs be visible directly on the website (like others do with NEPs, PEPs, etc.). Looking at the now formatted HEP, it has no title which won't help creating a web page out of it (I think the page title for all HEPs would be Summary?). Could we remove Identifer and Title from the table, and ask that the HEP title should be formatted as # {Identifier} - {Title}? Like NEPs.

[jbednar]

Looks good! I've made a series of changes you can consider that treats "enhancement" as being either a change or a formalization/codification of existing practice to improve clarity or streamline processes. Accordingly, numerous instances of the word "change" were replaced with "enhancement" or one of the two specific alternatives.

If people find this approach awkward, I'm perfectly ok with a section at the front that says that in this document a "change" could either be an actual change in policy or practice, or simply a change in how well something has been documented or formalized. But if you do that, using "change" as the universal term for an HEP, then I'd argue that it should be "HCP", i.e., that all of them are change requests. So I'm honoring the "E" in "HEP" by treating all of them as "enhancements", only some of which are actual changes. Someone else can decide if they agree with that approach!

[droumis]

@maximlt

Looking at the now formatted HEP, it has no title which won't help creating a web page out of it (I think the page title for all HEPs would be Summary?). Could we remove Identifer and Title from the table, and ask that the HEP title should be formatted as # {Identifier} - {Title}?

I updated the HEPs and the template to include a title. I would prefer to leave those rows in the table.

[maximlt]

@maximlt

Looking at the now formatted HEP, it has no title which won't help creating a web page out of it (I think the page title for all HEPs would be Summary?). Could we remove Identifer and Title from the table, and ask that the HEP title should be formatted as # {Identifier} - {Title}?

I updated the HEPs and the template to include a title. I would prefer to leave those rows in the table.

Ok, fine by me!

[ahuang11]

Looks mostly good; couple comments:

Is HEP1 missing: * Resolution -- A short summary of the decision made by the community.

Can we also put ## Resolution / Decision as a section, or at least within Summary, e.g. precisely what was adopted?

Lastly, how do we ensure that HoloViz maintainers have seen this? When I joined, I wasn't aware of HEPs.

[droumis]

Is HEP1 missing: * Resolution -- A short summary of the decision made by the community.
Can we also put ## Resolution / Decision as a section, or at least within Summary, e.g. precisely what was adopted?

Currently, the resolution section is only recommended, not required. For HEP 1, I personally think the link to the GitHub PR in the table provides sufficient context for the community discussion that took place, which wasn't too much. But I've gone ahead and added a Resolution section under the summary for HEP 1.

Lastly, how do we ensure that HoloViz maintainers have seen this? When I joined, I wasn't aware of HEPs.

Maybe we can link to this HEP 0 from the governance documents. All HoloViz maintainers should read the governance to which they are bound, so it seems like a good place to make any new-comers aware of HEPs. But I think this is beyond discussion of HEP 0.

[ahuang11]

Currently, the resolution section is only recommended, not required

I'm leaning towards it should be required, or at least a Specification on what maintainers should be doing in the future.

I imagine in the future there could be 100 HEPs; someone will not be able to read all that and their discussions. so, having a section that clearly outlines what each HEP is putting forward or whats required of maintainers would make things a whole lot more manageable.

Maybe we can link to this HEP 0 from the governance documents

:) No one really told me anything about the governance docs either...

[maximlt]

Lastly, how do we ensure that HoloViz maintainers have seen this? When I joined, I wasn't aware of HEPs.

I wrote https://holoviz.org/contributing.html#operating-guide for HoloViz maintainers, I think it could be updated to introduce HEPs and point to HEPs relevant to maintainers.

[droumis]

I'm leaning towards it should be required, or at least a Specification on what maintainers should be doing in the future.

I imagine in the future there could be 100 HEPs; someone will not be able to read all that and their discussions. so, having a section that clearly outlines what each HEP is putting forward or whats required of maintainers would make things a whole lot more manageable.

OK, I'll make the Specification/Policy required for prescriptive HEPs. But in order to understand what "precisely what was adopted", I don't think we can impose making it into a short summary. Besides, I don't think it's intended that a new contributor read through 100 HEPs, but rather that the HEPs are accessible enough and their topic sufficiently-encapsulated by the title, such that if a question arises at a HoloViz meeting (e.g. should we drop support for python X.X), that someone will remember that there is a HEP on this topic that can be used as guidance.

[maximlt]

I will be updating #388 in light of the proposed changes here. I think it'll help us gauge whether authoring a HEP hard following the format isn't too hard (I hope not! It shouldn't be, otherwise people will take other approaches).

[droumis]

@maximlt , since this hasn't been merged yet, please provide feedback as you update #388 so we can adjust accordingly

[maximlt]

@maximlt , since this hasn't been merged yet, please provide feedback as you update #388 so we can adjust accordingly

I updated it, mostly moving around text, and stuffing most of it under Specification. If you have time to have a quick look at HEP2 and see if I did that in a correct-ish way?

[droumis]

thanks for the input, team. merging now