Skip to content

Commit 0fb1acf

Browse files
wkswks
authored
MMTk Enhancement Proposal (#1056)
This PR adds a document that describes the MMTk Enhancement Proposal (MEP).
1 parent 79fb0bb commit 0fb1acf

File tree

2 files changed

+369
-0
lines changed

2 files changed

+369
-0
lines changed

‎.github/ISSUE_TEMPLATE/mmtk-enhancememnt-proposal--mep-.md

+125
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
name: MMTk Enhancememnt Proposal (MEP)
3+
about: Use this template to create an MMTk Enhancement Proposal (MEP).
4+
title: ''
5+
labels: MEP
6+
assignees: ''
7+
8+
---
9+
10+
# TL;DR
11+
12+
This section should use about one to three sentences to summarize the MEP. As the name "TL;DR" (too
13+
long, didn't read) suggests, this section should be short enough so that readers (including those in
14+
a hurry) can get the main idea very quickly without reading through the MEP.
15+
16+
# Goal
17+
18+
What are the goals of the proposal? This should be succinct. If there's more than one goal,
19+
enumerate them in a list.
20+
21+
- goal 1
22+
- goal 2
23+
- ...
24+
25+
# Non-goal
26+
27+
Optional. Use this section to explicitly exclusive goals out of the scope of the current MEP.
28+
29+
- non-goal 1
30+
- non-goal 2
31+
- ...
32+
33+
# Success Metric
34+
35+
How do we determine whether the MEP is a success? This can include improvements in performance,
36+
safety, readability, maintainability, etc. Enumerate the success metrics in a list (details should
37+
be in the *Description* section).
38+
39+
# Motivation
40+
41+
Why should this work be done? Who is asking for it?
42+
43+
Make sure the readers understand the problem this MEP is trying to address. You can also mention
44+
the languages, VMs, or users that need this enhancement.
45+
46+
If there are alternative ways to solve the problem, you can mention them here, but keep in mind that
47+
there is an *Alternatives* section for adding more details.
48+
49+
# Description
50+
51+
This is the main section of the MEP. Describe the enhancement in detail.
52+
53+
If you have already made prototype implementations for this MEP, add hyperlinks to the relevant PRs,
54+
commits, repositories, etc.
55+
56+
If not, describe how you intend to implement this MEP. You should think about all parts of
57+
mmtk-core that your MEP may interact with.
58+
59+
This section will be long. Feel free to add more subsections.
60+
61+
## Impact on Performance
62+
63+
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.
64+
65+
## Impact on Software Engineering
66+
67+
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?
68+
69+
# Risks
70+
71+
In the following sub-sections, outline the *long-term* risks posed by this MEP and how those risks are mitigated. **The core
72+
purpose of the MEP process is to avoid the unintentional introduction of changes that bring
73+
long-term negative impacts to MMTk**. This section is about identifying and accounting for risks
74+
associated with such negative outcomes. It should include the following subsections:
75+
76+
## Long Term Performance Risks
77+
78+
Enumerate possible negative long-term performance impacts of this MEP, and for each explain how that
79+
risk will be mitigated. Note: this is *not* about the immediate performance impact of the MEP,
80+
but about the impact on future work. For example, this includes identifying changes that may impede
81+
the future introduction of entirely new algorithms, or entirely new optimizations.
82+
83+
It is OK for us to accept temporary minor performance reduction to make more significant
84+
improvements possible. On the contrary, it is bad to make changes to temporarily improve
85+
performance and make long-term improvements hard or impossible.
86+
87+
## Long Term Software Engineering Risks
88+
89+
Enumerate possible negative long-term software engineering impacts of this MEP, and for each explain
90+
how that risk will be mitigated.
91+
92+
One of the core goals of MMTk is making GC development easy. If a developer wants to develop, for
93+
example, a new GC algorithm, it should be easy to implement it quickly and easily in MMTk. We don't
94+
want changes that make this difficult.
95+
96+
## Impact on API
97+
98+
Outline how this MEP will affect APIs, both public and internal. Enumerate the cases, and for each
99+
case, explain how the risk of negative consequences will be mitigated and/or justify the change.
100+
101+
# Testing
102+
103+
If applicable, describe the way to reproduce the problem, and the way to check if the change
104+
actually works. For MMTk, it includes but is not limited to what (micro or macro) benchmarks to
105+
use, and which VM binding (with or without changes) to use.
106+
107+
# Alternatives
108+
109+
Optional. If there are more than one way to solve the problem, describe them here and explain why
110+
this approach is preferred.
111+
112+
# Assumptions
113+
114+
Optional. For the design changes of MMTk, this part mainly includes assumptions about, for example,
115+
the VM's requirements, the GC algorithms we are supporting, the OS/architecture MMTK is running on,
116+
etc. If those assumptions no longer hold, we may need to reconsider the design. Describe such
117+
concerns in this section.
118+
119+
# Related Issues
120+
121+
Optional. If there are related issues, PRs, etc., include them here.
122+
123+
Sometimes people create ordinary issues and PRs to fix some problems, and later MMTk developers
124+
consider that the change is too fundamental and needs a more thorough reviewing process. If that is
125+
the case, add hyperlinks to those original issues and PRs.

‎docs/contribute/mep.md

+244
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
MMTk Enhancement Proposal (MEP)
2+
===============================
3+
4+
An MMTk Enhancement Proposal (MEP) is a formal process for the MMTk team and its developers to
5+
propose significant design changes, review the impact of the changes and make informed decisions.
6+
It has a special format, and will undergo a more thorough review process. Its goal is helping the
7+
MMTk developers making more informed decisions.
8+
9+
MEP is inspired by the Java Enhancement Proposal, described in https://openjdk.org/jeps/1
10+
11+
# When is MEP required?
12+
13+
An MEP is required when making a significant change to the design of the MMTk core. It is
14+
applicable to any kind of significant changes, including but not limited to:
15+
16+
- Bug fixes, including performance bug fixes, that require change to a major part of the MMTk
17+
core.
18+
- Changes to the MMTk core to implement a feature demanded by bindings.
19+
- Major refactoring to the MMTk core.
20+
21+
**The core purpose of the MEP process is to avoid the unintentional introduction of changes that
22+
bring long-term negative impacts to MMTk.** Large-scale changes and public API changes usually
23+
indicate such risks, but these are only indicators, not criteria. The assessment of risks is mostly
24+
subjective, and the MMTk team need to discuss in order to reach consensus.
25+
26+
If a contributor is uncertain if they should submit an MEP for their proposed changes, we encourage
27+
them to talk with the MMTk team first, or to simply submit a normal PR/issue to get it started. An
28+
MEP would be requested by the MMTk team if necessary (See the details about this in the section of
29+
MEP review process).
30+
31+
# Format
32+
33+
A MEP will be posted as a GitHub issue in the `mmtk-core` repository. It should contain `MEP` tag.
34+
35+
A MEP should have the following sections:
36+
37+
- TL;DR
38+
- Goal
39+
- Non-goal (optional)
40+
- Success Metric
41+
- Motivation
42+
- Description
43+
- Impact on Performance
44+
- Impact on Software Engineering
45+
- Risks
46+
- Long Term Performance Risks
47+
- Long Term Software Engineering Risks
48+
- Impact on API
49+
- Testing
50+
- Alternatives (optional)
51+
- Risks and Assumptions (optional)
52+
- Related Issues (optional)
53+
54+
# Sections
55+
56+
## TL;DR
57+
58+
This section should use about one to three sentences to summarize the MEP. As the name "TL;DR" (too
59+
long, didn't read) suggests, this section should be short enough so that readers (including those in
60+
a hurry) can get the main idea very quickly without reading through the MEP.
61+
62+
## Goals
63+
64+
What are the goals of the proposal? This should be succinct. If there's more than one goal,
65+
enumerate them in a list.
66+
67+
## Non-Goals
68+
69+
Optional. Use this section to explicitly exclusive goals out of the scope of the current MEP.
70+
71+
## Success Metric
72+
73+
How do we determine whether the MEP is a success? This can include improvements in performance,
74+
safety, readability, maintainability, etc. Enumerate the success metrics in a list (details should
75+
be in the *Description* section).
76+
77+
## Motivation
78+
79+
Why should this work be done? Who is asking for it?
80+
81+
Make sure the readers understand the problem this MEP is trying to address. You can also mention
82+
the languages, VMs, or users that need this enhancement.
83+
84+
If there are alternative ways to solve the problem, you can mention them here, but keep in mind that
85+
there is an *Alternatives* section for adding more details.
86+
87+
## Description
88+
89+
This is the main section of the MEP. Describe the enhancement in detail.
90+
91+
If you have already made prototype implementations for this MEP, add hyperlinks to the relevant PRs,
92+
commits, repositories, etc.
93+
94+
If not, describe how you intend to implement this MEP. You should think about all parts of
95+
mmtk-core that your MEP may interact with.
96+
97+
This section will be long, and will usually be divided into many subsections. The following
98+
subsections must be included:
99+
100+
- Impact on Performance
101+
- Impact on Software Engineering
102+
103+
### Impact on Performance
104+
105+
Describe how this MEP will affect the performance. "This MEP should not have any impact on
106+
performance" is still a valid description if it is so.
107+
108+
### Impact on Software Engineering
109+
110+
Describe whether this MEP will make software engineering easier or more difficult. Will it make the
111+
code easier or harder to understand, maintain and/or change?
112+
113+
## Risks
114+
115+
Outline the *long-term* risks posed by this MEP and how those risks are mitigated. **The core
116+
purpose of the MEP process is to avoid the unintentional introduction of changes that bring
117+
long-term negative impacts to MMTk**. This section is about identifying and accounting for risks
118+
associated with such negative outcomes. It should include the following subsections:
119+
120+
- Long Term Performance Risks
121+
- Long Term Software Engineering Risks
122+
- Impact on API
123+
124+
### Long Term Performance Risks
125+
126+
Enumerate possible negative long-term performance impacts of this MEP, and for each explain how that
127+
risk will be mitigated. Note: this is *not* about the immediate performance impact of the MEP,
128+
but about the impact on future work. For example, this includes identifying changes that may impede
129+
the future introduction of entirely new algorithms, or entirely new optimizations.
130+
131+
It is OK for us to accept temporary minor performance reduction to make more significant
132+
improvements possible. On the contrary, it is bad to make changes to temporarily improve
133+
performance and make long-term improvements hard or impossible.
134+
135+
### Long Term Software Engineering Risks
136+
137+
Enumerate possible negative long-term software engineering impacts of this MEP, and for each explain
138+
how that risk will be mitigated.
139+
140+
One of the core goals of MMTk is making GC development easy. If a developer wants to develop, for
141+
example, a new GC algorithm, it should be easy to implement it quickly and easily in MMTk. We don't
142+
want changes that make this difficult.
143+
144+
### Impact on API
145+
146+
Outline how this MEP will affect APIs, both public and internal. Enumerate the cases, and for each
147+
case, explain how the risk of negative consequences will be mitigated and/or justify the change.
148+
149+
## Testing
150+
151+
If applicable, describe the way to reproduce the problem, and the way to check if the change
152+
actually works. For MMTk, it includes but is not limited to what (micro or macro) benchmarks to
153+
use, and which VM binding (with or without changes) to use.
154+
155+
## Alternatives
156+
157+
Optional. If there are more than one way to solve the problem, describe them here and explain why
158+
this approach is preferred.
159+
160+
## Assumptions
161+
162+
Optional. For the design changes of MMTk, this part mainly includes assumptions about, for example,
163+
the VM's requirements, the GC algorithms we are supporting, the OS/architecture MMTK is running on,
164+
etc. If those assumptions no longer hold, we may need to reconsider the design. Describe such
165+
concerns in this section.
166+
167+
## Related Issues
168+
169+
Optional. If there are related issues, PRs, etc., include them here.
170+
171+
Sometimes people create ordinary issues and PRs to fix some problems, and later MMTk developers
172+
consider that the change is too fundamental and needs a more thorough reviewing process. If that is
173+
the case, add hyperlinks to those original issues and PRs.
174+
175+
# MEP Reviewing Process
176+
177+
## Initiate an MEP
178+
179+
An MEP is initiated by creating an MEP issue with the format described in this document.
180+
181+
### Escalate normal PRs/issues and request for MEP
182+
183+
For normal PRs/issues, if any team member thinks it should be an MEP, they should escalate it and
184+
discuss with the team. If the team decide that it should be an MEP, the PR/issue should be set to
185+
'Request for MEP', and expects an MEP issue from the contributor. If there is no further action from
186+
the contributor for a period of time, the PR/issue is considered as stale and it may get assigned to
187+
an MMTk team member or may be closed.
188+
189+
Note that a team member may escalate an PR/issue for normal discussion, rather than requesting for
190+
MEP. As we discussed, MEP is a heavy-weight process, and we should not abuse requesting it.
191+
192+
## Review an MEP
193+
194+
### Criteria
195+
196+
The MMTk team will first decide if the proposal meets the criteria for being an MEP. If it does not
197+
meet the criteria, the proposal issue will be closed, and related changes should be treated as a
198+
normal PR/issue.
199+
200+
The criteria for what need to be an MEP is mostly subjective, based on a consensus model within the
201+
MMTk team. We also provide a list of exemption for what do not need to be an MEP.
202+
203+
#### MEP Exemption
204+
205+
MEP is intended to help avoid design changes that may have profound negative impact in the future.
206+
Some changes will not have profound impact, and can be easily reverted if necessary. They should be
207+
exempt from the heavy-weight MEP process, and should not be escalated to request for MEP. The
208+
exemption is intended to ensure that we won't abuse using MEP and that we won't impose burden on the
209+
contributors to submit an extra MEP proposal. An exempted PR may still be escalated for team
210+
discussion, but it is exempt from being requested for MEP (submitting a MEP proposal, and going
211+
through the MEP process).
212+
213+
##### Exemption 1: Well-encapsulated changes
214+
215+
Changes that are well-encapsulated and decoupled intrinsically can be easily corrected in the future
216+
and will not have profound impact for the future. A PR that has no public API change, and no module
217+
API change between the top-level modules (`plan`, `policy`, `scheduler`, `util` and `vm` at the time
218+
of writing) is exempt from MEP.
219+
220+
### Review
221+
222+
The MMTk team will discuss the proposal in weekly meetings. This process may take a while. We will
223+
keep posting the discussion to the MEP issue, and encourage further inputs from the contributor, and
224+
the community. An MEP may get updated and refined during the process.
225+
226+
### Outcome
227+
228+
At the end of the review, the MEP will be accepted or rejected based on the consensus of the MMTk
229+
team. If an MEP is accepted, A PR may follow the MEP and will be reviewed with the normal PR review
230+
process.
231+
232+
If an MEP is rejected, future related MEPs may not be reviewed again unless they are substantially
233+
different. We encourage people to get involved in the review discussion, and refine the proposal so
234+
it will be accepted.
235+
236+
## Communication
237+
238+
After an MEP is implemented, the MMTk team shall announce the significant changes as the results of
239+
the MEP to make them known to the community. We shall communicate with our sponsors about such
240+
changes, too, in our regular meetings.
241+
242+
<!--
243+
vim: ts=4 sw=4 sts=4 et tw=100
244+
-->

0 commit comments

Comments
 (0)