Description
MMTk Enhancement Proposal (MEP)
This is a draft. We decided to try this process for three months, and review whether this process is good enough or needs changing.
This is a meta-issue that describes the format and process of MEP.
TODO: After trial, we should put a formal version of this document in mmtk-core/docs
.
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 assesment 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, 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 ofC-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 (optional)
- Motivation
- Description
- Impact on Performance
- Impact on Future Performance Improvement
- Impact on Public API
- Impact on Software Engineering
- Testing (optional)
- 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.
Goal
What are the goals of the proposal? Preferrably enumerate the goals in a list.
Non-Goals
Optional. Use this section to explicitly exclusive goals out of the scope of the current MEP.
Success Metric
Optional. What profits this MEP will bring after it is implemented? This can incldue improvements in performance, safety, readability, maintainability, etc. Enumerate the profits in a list, but describe the details 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, repos, 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 should include several subsections:
- Impact on Performance
- Impact on Future Performance Improvement
- Impact on Public API
- 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 Future Performance Improvement
Describe whether this MEP will bring any opportunity or difficulty for improving the performance of MMTk in the future.
The immediate performance impact is important, but a more important thing is the long-term opportunity to improve performance in the future (See the next subsection). 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 imporovements hard or impossible.
Impact on Public API
Describe how this MEP will change the public API. "This MEP makes no change to the public API" 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?
One goal 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 generally don't want changes that make this difficult.
Testing
Optional. 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 limitied 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.
Risks and 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.
Reviewing Process
TODO