Skip to content

Commit 32be84d

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

File tree

1 file changed

+34
-1
lines changed

1 file changed

+34
-1
lines changed

news/instructions.md

Lines changed: 34 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,23 @@ 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 notworthy new feature
50+
<!-- Optional link(s) to issues or PRs as invisible comment -->
51+
contributed by [John Doe](https://github.com/ghost)
52+
***
53+
54+
Describe the change here.
55+
See the instructions in the paragraphs below regarding style recommendation and things to consider.
56+
You can use all markdown features and, if required and supported, inline HTML.
57+
58+
An image can say more than a thousand words:
59+
![Foo View](images/foo-view.png)
60+
```
61+
3962
### News Item Title and Description
4063

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

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

6487
Use active voice, i.e., say "you", not "the user",
6588
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 +162,16 @@ but the label can be interesting unless it's already part of the description.
139162

140163
Use regular markdown for the image so it can be appropriately rendered and styled.
141164

165+
### Contributor Mentioning
166+
167+
The individuals that have contributed to a noteworthy change _can_ be mentioned as contributors of it.
168+
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).
169+
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.
170+
If anybody other than the author of the N&N entry is listed, that person's consent should be obtained
171+
(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).
172+
Every individual who made code contributions to the described change should be mentioned as contributors (if consented).
173+
If too many people contributed to a change and the list becomes too long it can be [collapsed](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
174+
or no contributor could be mentioned at all.
142175

143176
### Initialization
144177

0 commit comments

Comments
 (0)