From 71bb2dfe6b745c24f06bf62f45fd20f5fd90f8b7 Mon Sep 17 00:00:00 2001 From: Kunshan Wang Date: Thu, 21 Dec 2023 16:21:59 +0800 Subject: [PATCH 1/3] MMTk Enhancement Proposal --- docs/team/mep.md | 265 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) create mode 100644 docs/team/mep.md diff --git a/docs/team/mep.md b/docs/team/mep.md new file mode 100644 index 0000000000..51d5532bbf --- /dev/null +++ b/docs/team/mep.md @@ -0,0 +1,265 @@ +MMTk Enhancement Proposal (MEP) +=============================== + +An MMTk Enhancement Proposal (MEP) is a more formal variant of issue. It has a special format, and +will undergo a more thorough review process. Its goal is helping the MMTk developers making more +informed decisions. + +MEP is inspired by the Java Enhancement Proposal, described in https://openjdk.org/jeps/1 However, +unlike JEP which is more open-ended, MEP is more focused on making design decisions. + +# When is MEP required? + +An MEP is required when making a significant change to the design of the MMTk core. It is +applicable to any kind of significant changes, including but not limited to: + +- Bug fixes, including performance bug fixes, that require change to a major part of the MMTk + core. +- Changes to the MMTk core to implement a feature demanded by bindings. +- Major refactoring to the MMTk core. + +One purpose of MEP is reducing the risks to the future development of MMTk. Large-scale changes and +public API changes usually indicate such risks, but these are only indicators, not criteria. The +assessment of risks is subjective, and we need to discuss in order to reach consensus. + +Note: JEP is also required for things that "require two or more weeks of engineering effort" and/or +"are in high demand by developers or customers". We don't judge whether we need MEP based on +engineering effort or public demand. Many PRs for MMTk require multiple weeks of work and rigorous +testing, but most of them can be settled with regular issues and PRs. We label priorities using +GitHub issue tags, such as `P-normal`, `P-high`, etc. If a feature is requested often, and we have +man power for that, we can raise the priority. + +# Format + +A MEP will be posted as a GitHub issue in the `mmtk-core` repository. It should contain certain +tags: + +- **The `MEP` tag** + - It is used to identify MEPs. +- **Area (`A-*`)** + - For example, `A-gc-algorithm`. +- **Category (`C-*`)** + - For example, `C-refactoring`. + - Note that not all MEP are "enhancement" in the sense of `C-enhancement`. Some MEPs may + simply be intended for fixing long-standing hard-to-fix bugs by making non-trivial changes. +- **Goal (`G-*`)** + - For example, `G-safety`. + +We use the format of JEP (https://openjdk.org/jeps/2) as a frame of reference, but deviate from it +when needed. + +A MEP should have the following sections: + +- TL;DR (summary) +- Goal +- Non-goal (optional) +- Success Metric +- Motivation +- Description + - Impact on Performance + - Impact on Software Engineering +- Risks + - Long Term Performance Risks + - Long Term Software Engineering Risks + - Impact on API +- Testing +- Alternatives (optional) +- Risks and Assumptions (optional) +- Related Issues (optional) + +Note: Sections in JEP but not in MEP: + +- Dependencies: We have the *Related Issues* section, instead. + +# Sections + +## TL;DR + +This section should use about one to three sentences to summarize the MEP. JEP calls it "Summary", +but we call it "TL;DR" (too long, didn't read) to emphasize that it should be short enough so that +readers (including those in a hurry) can get the main idea very quickly without reading through the +MEP. + +## Goals + +What are the goals of the proposal? This should be succinct. If there's more than one goal, +enumerate them in a list. + +## Non-Goals + +Optional. Use this section to explicitly exclusive goals out of the scope of the current MEP. + +## Success Metric + +How do we determine whether the MEP is a success? This can include improvements in performance, +safety, readability, maintainability, etc. Enumerate the success metrics in a list (details should +be in the *Description* section). + +## Motivation + +Why should this work be done? Who is asking for it? + +Make sure the readers understand the problem this MEP is trying to address. You can also mention +the languages, VMs, or users that need this enhancement. + +If there are alternative ways to solve the problem, you can mention them here, but keep in mind that +there is an *Alternatives* section for adding more details. + +## Description + +This is the main section of the MEP. Describe the enhancement in detail. + +If you have already made prototype implementations for this MEP, add hyperlinks to the relevant PRs, +commits, repositories, etc. + +If not, describe how you intend to implement this MEP. You should think about all parts of +mmtk-core that your MEP may interact with. + +This section will be long, and will usually be divided into many subsections. The following +subsections must be included: + +- Impact on Performance +- Impact on Software Engineering + +### Impact on Performance + +Describe how this MEP will affect the performance. "This MEP should not have any impact on +performance" is still a valid description if it is so. + +### Impact on Software Engineering + +Describe whether this MEP will make software engineering easier or more difficult. Will it make the +code easier or harder to understand, maintain and/or change? + +## Risks + +Outline the *long-term* risks posed by this MEP and how those risks are mitigated. **The core +purpose of the MEP process is to avoid the unintentional introduction of changes that bring +long-term negative impacts to MMTk**. This section is about identifying and accounting for risks +associated with such negative outcomes. It should include the following subsections: + +- Long Term Performance Risks +- Long Term Software Engineering Risks +- Impact on API + +### Long Term Performance Risks + +Enumerate possible negative long-term performance impacts of this MEP, and for each explain how that +risk will be mitigated. Note: this is *not* about the immediate performance impact of the MEP, +but about the impact on future work. For example, this includes identifying changes that may impede +the future introduction of entirely new algorithms, or entirely new optimizations. + +It is OK for us to accept temporary minor performance reduction to make more significant +improvements possible. On the contrary, it is bad to make changes to temporarily improve +performance and make long-term improvements hard or impossible. + +### Long Term Software Engineering Risks + +Enumerate possible negative long-term software engineering impacts of this MEP, and for each explain +how that risk will be mitigated. + +One of the core goals of MMTk is making GC development easy. If a developer wants to develop, for +example, a new GC algorithm, it should be easy to implement it quickly and easily in MMTk. We don't +want changes that make this difficult. + +### Impact on API + +Outline how this MEP will affect APIs, both public and internal. Enumerate the cases, and for each +case, explain how the risk of negative consequences will be mitigated and/or justify the change. + +## Testing + +If applicable, describe the way to reproduce the problem, and the way to check if the change +actually works. For MMTk, it includes but is not limited to what (micro or macro) benchmarks to +use, and which VM binding (with or without changes) to use. + +## Alternatives + +Optional. If there are more than one way to solve the problem, describe them here and explain why +this approach is preferred. + +## Assumptions + +Optional. For the design changes of MMTk, this part mainly includes assumptions about, for example, +the VM's requirements, the GC algorithms we are supporting, the OS/architecture MMTK is running on, +etc. If those assumptions no longer hold, we may need to reconsider the design. Describe such +concerns in this section. + +## Related Issues + +Optional. If there are related issues, PRs, etc., include them here. + +Sometimes people create ordinary issues and PRs to fix some problems, and later MMTk developers +consider that the change is too fundamental and needs a more thorough reviewing process. If that is +the case, add hyperlinks to those original issues and PRs. + +# MEP Reviewing Process + +## Initiate an MEP + +An MEP is initiated by creating an MEP issue with the format described in this document. + +### Escalate normal PRs/issues and request for MEP + +For normal PRs/issues, if any team member thinks it should be an MEP, they should escalate it and +discuss with the team. If the team decide that it should be an MEP, the PR/issue should be set to +'Request for MEP', and expects an MEP issue from the contributor. If there is no further action from +the contributor for a period of time, the PR/issue is considered as stale and it may get assigned to +an MMTk team member or may be closed. + +Note that a team member may escalate an PR/issue for normal discussion, rather than requesting for +MEP. As we discussed, MEP is a heavy-weight process, and we should not abuse requesting it. + +## Review an MEP + +### Criteria + +The MMTk team will first decide if the proposal meets the criteria for being an MEP. If it does not +meet the criteria, the proposal issue will be closed, and related changes should be treated as a +normal PR/issue. + +The criteria for what need to be an MEP is mostly subjective, based on a consensus model within the +MMTk team. We also provide a list of exemption for what do not need to be an MEP. + +#### MEP Exemption + +MEP is intended to help avoid design changes that may have profound negative impact in the future. +Some changes will not have profound impact, and can be easily reverted if necessary. They should be +exempt from the heavy-weight MEP process, and should not be escalated to request for MEP. The +exemption is intended to ensure that we won't abuse using MEP and that we won't impose burden on the +contributors to submit an extra MEP proposal. An exempted PR may still be escalated for team +discussion, but it is exempt from being requested for MEP (submitting a MEP proposal, and going +through the MEP process). + +##### Exemption 1: Well-encapsulated changes + +Changes that are well-encapsulated and decoupled intrinsically can be easily corrected in the future +and will not have profound impact for the future. A PR that has no public API change, and no module +API change between the top-level modules (`plan`, `policy`, `scheduler`, `util` and `vm` at the time +of writing) is exempt from MEP. + +### Review + +The MMTk team will discuss the proposal in weekly meetings. This process may take a while. We will +keep posting the discussion to the MEP issue, and encourage further inputs from the contributor, and +the community. An MEP may get updated and refined during the process. + +### Outcome + +At the end of the review, the MEP will be accepted or rejected based on the consensus of the MMTk +team. If an MEP is accepted, A PR may follow the MEP and will be reviewed with the normal PR review +process. + +If an MEP is rejected, future related MEPs may not be reviewed again unless they are substantially +different. We encourage people to get involved in the review discussion, and refine the proposal so +it will be accepted. + +## Communication + +After an MEP is implemented, the MMTk team shall announce the significant changes as the results of +the MEP to make them known to the community. We shall communicate with our sponsors about such +changes, too, in our regular meetings. + + From 7841550371b012945c545ac84d27669e0fec3990 Mon Sep 17 00:00:00 2001 From: Kunshan Wang Date: Fri, 22 Dec 2023 09:42:04 +0800 Subject: [PATCH 2/3] Moved mep.md to a different directory --- docs/{team => contribute}/mep.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{team => contribute}/mep.md (100%) diff --git a/docs/team/mep.md b/docs/contribute/mep.md similarity index 100% rename from docs/team/mep.md rename to docs/contribute/mep.md From abd71e2d9f0935225f32add8e15d4a949956d617 Mon Sep 17 00:00:00 2001 From: Kunshan Wang Date: Fri, 22 Dec 2023 10:31:21 +0800 Subject: [PATCH 3/3] Update MEP doc and add MEP template --- .../mmtk-enhancememnt-proposal--mep-.md | 125 ++++++++++++++++++ docs/contribute/mep.md | 57 +++----- 2 files changed, 143 insertions(+), 39 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/mmtk-enhancememnt-proposal--mep-.md diff --git a/.github/ISSUE_TEMPLATE/mmtk-enhancememnt-proposal--mep-.md b/.github/ISSUE_TEMPLATE/mmtk-enhancememnt-proposal--mep-.md new file mode 100644 index 0000000000..acfb7b87a2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/mmtk-enhancememnt-proposal--mep-.md @@ -0,0 +1,125 @@ +--- +name: MMTk Enhancememnt Proposal (MEP) +about: Use this template to create an MMTk Enhancement Proposal (MEP). +title: '' +labels: MEP +assignees: '' + +--- + +# TL;DR + +This section should use about one to three sentences to summarize the MEP. As the name "TL;DR" (too +long, didn't read) suggests, this section should be short enough so that readers (including those in +a hurry) can get the main idea very quickly without reading through the MEP. + +# Goal + +What are the goals of the proposal? This should be succinct. If there's more than one goal, +enumerate them in a list. + +- goal 1 +- goal 2 +- ... + +# Non-goal + +Optional. Use this section to explicitly exclusive goals out of the scope of the current MEP. + +- non-goal 1 +- non-goal 2 +- ... + +# Success Metric + +How do we determine whether the MEP is a success? This can include improvements in performance, +safety, readability, maintainability, etc. Enumerate the success metrics in a list (details should +be in the *Description* section). + +# Motivation + +Why should this work be done? Who is asking for it? + +Make sure the readers understand the problem this MEP is trying to address. You can also mention +the languages, VMs, or users that need this enhancement. + +If there are alternative ways to solve the problem, you can mention them here, but keep in mind that +there is an *Alternatives* section for adding more details. + +# Description + +This is the main section of the MEP. Describe the enhancement in detail. + +If you have already made prototype implementations for this MEP, add hyperlinks to the relevant PRs, +commits, repositories, etc. + +If not, describe how you intend to implement this MEP. You should think about all parts of +mmtk-core that your MEP may interact with. + +This section will be long. Feel free to add more subsections. + +## Impact on Performance + +Describe how this MEP will affect the performance. "This MEP should not have any impact on performance" is still a valid description if it is so. + +## Impact on Software Engineering + +Describe whether this MEP will make software engineering easier or more difficult. Will it make the code easier or harder to understand, maintain and/or change? + +# Risks + +In the following sub-sections, outline the *long-term* risks posed by this MEP and how those risks are mitigated. **The core +purpose of the MEP process is to avoid the unintentional introduction of changes that bring +long-term negative impacts to MMTk**. This section is about identifying and accounting for risks +associated with such negative outcomes. It should include the following subsections: + +## Long Term Performance Risks + +Enumerate possible negative long-term performance impacts of this MEP, and for each explain how that +risk will be mitigated. Note: this is *not* about the immediate performance impact of the MEP, +but about the impact on future work. For example, this includes identifying changes that may impede +the future introduction of entirely new algorithms, or entirely new optimizations. + +It is OK for us to accept temporary minor performance reduction to make more significant +improvements possible. On the contrary, it is bad to make changes to temporarily improve +performance and make long-term improvements hard or impossible. + +## Long Term Software Engineering Risks + +Enumerate possible negative long-term software engineering impacts of this MEP, and for each explain +how that risk will be mitigated. + +One of the core goals of MMTk is making GC development easy. If a developer wants to develop, for +example, a new GC algorithm, it should be easy to implement it quickly and easily in MMTk. We don't +want changes that make this difficult. + +## Impact on API + +Outline how this MEP will affect APIs, both public and internal. Enumerate the cases, and for each +case, explain how the risk of negative consequences will be mitigated and/or justify the change. + +# Testing + +If applicable, describe the way to reproduce the problem, and the way to check if the change +actually works. For MMTk, it includes but is not limited to what (micro or macro) benchmarks to +use, and which VM binding (with or without changes) to use. + +# Alternatives + +Optional. If there are more than one way to solve the problem, describe them here and explain why +this approach is preferred. + +# Assumptions + +Optional. For the design changes of MMTk, this part mainly includes assumptions about, for example, +the VM's requirements, the GC algorithms we are supporting, the OS/architecture MMTK is running on, +etc. If those assumptions no longer hold, we may need to reconsider the design. Describe such +concerns in this section. + +# Related Issues + +Optional. If there are related issues, PRs, etc., include them here. + +Sometimes people create ordinary issues and PRs to fix some problems, and later MMTk developers +consider that the change is too fundamental and needs a more thorough reviewing process. If that is +the case, add hyperlinks to those original issues and PRs. diff --git a/docs/contribute/mep.md b/docs/contribute/mep.md index 51d5532bbf..083281d5f2 100644 --- a/docs/contribute/mep.md +++ b/docs/contribute/mep.md @@ -1,12 +1,12 @@ MMTk Enhancement Proposal (MEP) =============================== -An MMTk Enhancement Proposal (MEP) is a more formal variant of issue. It has a special format, and -will undergo a more thorough review process. Its goal is helping the MMTk developers making more -informed decisions. +An MMTk Enhancement Proposal (MEP) is a formal process for the MMTk team and its developers to +propose significant design changes, review the impact of the changes and make informed decisions. +It has a special format, and will undergo a more thorough review process. Its goal is helping the +MMTk developers making more informed decisions. -MEP is inspired by the Java Enhancement Proposal, described in https://openjdk.org/jeps/1 However, -unlike JEP which is more open-ended, MEP is more focused on making design decisions. +MEP is inspired by the Java Enhancement Proposal, described in https://openjdk.org/jeps/1 # When is MEP required? @@ -18,39 +18,23 @@ applicable to any kind of significant changes, including but not limited to: - Changes to the MMTk core to implement a feature demanded by bindings. - Major refactoring to the MMTk core. -One purpose of MEP is reducing the risks to the future development of MMTk. Large-scale changes and -public API changes usually indicate such risks, but these are only indicators, not criteria. The -assessment of risks is subjective, and we need to discuss in order to reach consensus. +**The core purpose of the MEP process is to avoid the unintentional introduction of changes that +bring long-term negative impacts to MMTk.** Large-scale changes and public API changes usually +indicate such risks, but these are only indicators, not criteria. The assessment of risks is mostly +subjective, and the MMTk team need to discuss in order to reach consensus. -Note: JEP is also required for things that "require two or more weeks of engineering effort" and/or -"are in high demand by developers or customers". We don't judge whether we need MEP based on -engineering effort or public demand. Many PRs for MMTk require multiple weeks of work and rigorous -testing, but most of them can be settled with regular issues and PRs. We label priorities using -GitHub issue tags, such as `P-normal`, `P-high`, etc. If a feature is requested often, and we have -man power for that, we can raise the priority. +If a contributor is uncertain if they should submit an MEP for their proposed changes, we encourage +them to talk with the MMTk team first, or to simply submit a normal PR/issue to get it started. An +MEP would be requested by the MMTk team if necessary (See the details about this in the section of +MEP review process). # Format -A MEP will be posted as a GitHub issue in the `mmtk-core` repository. It should contain certain -tags: - -- **The `MEP` tag** - - It is used to identify MEPs. -- **Area (`A-*`)** - - For example, `A-gc-algorithm`. -- **Category (`C-*`)** - - For example, `C-refactoring`. - - Note that not all MEP are "enhancement" in the sense of `C-enhancement`. Some MEPs may - simply be intended for fixing long-standing hard-to-fix bugs by making non-trivial changes. -- **Goal (`G-*`)** - - For example, `G-safety`. - -We use the format of JEP (https://openjdk.org/jeps/2) as a frame of reference, but deviate from it -when needed. +A MEP will be posted as a GitHub issue in the `mmtk-core` repository. It should contain `MEP` tag. A MEP should have the following sections: -- TL;DR (summary) +- TL;DR - Goal - Non-goal (optional) - Success Metric @@ -67,18 +51,13 @@ A MEP should have the following sections: - Risks and Assumptions (optional) - Related Issues (optional) -Note: Sections in JEP but not in MEP: - -- Dependencies: We have the *Related Issues* section, instead. - # Sections ## TL;DR -This section should use about one to three sentences to summarize the MEP. JEP calls it "Summary", -but we call it "TL;DR" (too long, didn't read) to emphasize that it should be short enough so that -readers (including those in a hurry) can get the main idea very quickly without reading through the -MEP. +This section should use about one to three sentences to summarize the MEP. As the name "TL;DR" (too +long, didn't read) suggests, this section should be short enough so that readers (including those in +a hurry) can get the main idea very quickly without reading through the MEP. ## Goals