Skip to content

Commit 20d0b8d

Browse files
committed
Define template for optional contributor mentioning in N&N entries
Resolves - https://gitlab.eclipse.org/eclipse-wg/ide-wg/community/-/issues/81
1 parent e92e90d commit 20d0b8d

File tree

1 file changed

+36
-1
lines changed

1 file changed

+36
-1
lines changed

news/instructions.md

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@ Last revised 2025-05-08.
77
### Content Organization
88

99
As of 4.36, New and Noteworthy is authored in markdown.
10+
The following markdown flavors are supported:
11+
- `Markdown 1.0`
12+
- [`Common Mark 0.31`](https://spec.commonmark.org/0.31.2/)
13+
- [`GitHub Flavored Markdown 0.29`](https://github.github.com/gfm/)
14+
15+
See also [GitHub's writing documentation](https://docs.github.com/en/get-started/writing-on-github).
1016

1117
#### Markdown Preview
1218

@@ -36,6 +42,27 @@ you can add a new section to the document to highlight a feature,
3642
but best to add a subsection.
3743
Keep an eye on the automatically-rendered Table of Contents.
3844

45+
#### Template
46+
47+
The following is a template describing the recommended basic structure of a N&N entry:
48+
```
49+
### A Noteworthy New Feature
50+
<!-- Optional link(s) to issues or PRs as invisible comment -->
51+
<details>
52+
<summary>Contributors</summary>
53+
54+
- [John Doe](https://github.com/ghost)
55+
</details>
56+
57+
Describe the change here.
58+
See the instructions in the paragraphs below regarding style recommendation and things to consider.
59+
You can use all markdown features and, if required and supported, inline HTML.
60+
61+
An image can say more than a thousand words:
62+
63+
![Foo View](images/foo-view.png)
64+
```
65+
3966
### News Item Title and Description
4067

4168
The whole entry should be a blurb pitched to the Eclipse end-user community,
@@ -59,7 +86,7 @@ and don't repeat yourself.
5986
The description should be complete sentences, with trailing punctuation.
6087

6188
Make the entry self-contained and mention API classes.
62-
Do not link to issues and don't promote individuals or third-party products.
89+
Do not link to issues and don't promote third-party products.
6390

6491
Use active voice, i.e., say "you", not "the user",
6592
and follow other advice in [Eclipse Doc Style Guide](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Eclipse_Doc_Style_Guide.md#topic-content).
@@ -139,6 +166,14 @@ but the label can be interesting unless it's already part of the description.
139166

140167
Use regular markdown for the image so it can be appropriately rendered and styled.
141168

169+
### Contributor Mentioning
170+
171+
The individuals that have contributed to a noteworthy change _can_ be mentioned as contributors of it.
172+
Contributors should be mentioned below the headline, and the name of each contributor can be backed by a link to that person's GitHub profile as suggested in the [template](#template).
173+
It's recommended to use real full names, in the spirit of an open and transparent community, but if desired, a contributor's pseudonym can be used as well.
174+
If anybody other than the author of the N&N entry is listed, that person's consent should be obtained
175+
(for regular contributors, who have been mentioned in other entries already, general consent can be assumed and it's sufficient to make them aware of a new entry with the possibility to object).
176+
Every individual who made code contributions to the described change should be mentioned as contributors (if consented).
142177

143178
### Initialization
144179

0 commit comments

Comments
 (0)