Define template for optional contributor mentioning in N&N entries

[HannesWell]

As we recently discussed about ways how to show better that the Eclipse developer community is very active, many different people are involved and to give contributors more fame, one idea is to add the possibility to add the involved contributors to a N&N entry as described in:

• https://gitlab.eclipse.org/eclipse-wg/ide-wg/community/-/issues/81

Currently this PR is in a state, to explore and discuss where to add such information ideally and therefore it just adds the suggested lines in two different styles:

1. At the beginning of the entry (screenshot below)
2. At the end of an entry (screenshot below)
3. Suggestions for other locations are more than welcome.

@HeikoKlare, @fedejeanne and @Michael5601 I just used some of your entries to just explore/discuss the possibilities.
Eventually my intention for this PR is to just add corresponding instructions and a small, yet complete example respectively template-entry in the instructions, that's why it's currently a draft.

@BeckerWdf and @danthe1st you where also interested in the topic on our past dev-calls, maybe this is interesting for you too.

Contributor mentioned after the headline and the bottom

Eventually only one will be used!
Click for full scale:

Contributor mentioned at the end

Click for full scale:

[danthe1st]

It seems like this shows up as a pretty big heading when it's rendered for one of the sections. I don't think the contributors should be a bigger heading than the actual section headings.

For one of the others, it looks better:

But for that one, I think you made the image a heading (and I don't have it set up in a way that renders images)...

I think you were intending to use horizontal rulers (which show up correctly in GitHub) but this doesn't seem right when I render it by running jwebserver.

[Michael5601]

I did not contribute to develop the multi-monitor-scaling. Only the SVG Feature.
Besides that I like the idea. :)

[HeikoKlare]

I did not contribute to develop the multi-monitor-scaling. Only the SVG Feature.
Besides that I like the idea. :)

Adding on that for the sake of correctness if someone comes by: the monitor-specific scaling feature is primarily contributed by @akoch-yatta, @amartya4256, @ShahzaibIbrahim

Besides that I also really like the idea and would be in favor of adding the contributors right after the title line. That's also how many paper or online articles look like: the title is followed by a mentioned of the author before tha actual content.

Two primary question arise for me:

• Optional vs. mandatory: should this mention be something optional? If yes, who decides if it is added? Not every N&N is contributed by the contributor of a feature, some of them "we" write on our own to make aware of a new feature. Should we then mention the contributors or not? Do we need their agreement on that?
• Correctness: we need to be even more thorough on checking the N&N in the future to ensure that the correct (and all) contributors are mentioned. If the contributor information in the news is not correct, it will do more harm than help. And this is not even easy. I above pointed to further people who have recently contributed to the monitor-specific scaling. But actually contributions to that (mentioned in according issues) go back some years with even further people having made contributions, so where to draw the line? Regarding that specific feature, the major contributors did dozens of PRs while others only did one, but should only the "primary" contributors be mentioned then? Maybe I am "too afraid" and such a long-running feature is rather seldom, but I would like to avoid that while giving some people more fame we also demotivate others if they stay unmentioned even though they have made contributions.

In addition I am wondering whether this may influence for which feature news are written. News are supposed to be provided for the primary features of a release that consumers should know about (even though we don't have a precise definition when a feature has that "importance"). Adding the opportunity for mentioning the contributors in the news gives another, potentially conflicting incentive to writing the news, such that we may end up with rather unimportant news just to have a contributor mentioned. But to be honest, I don't see this as a risk as I also don't see that we will really get completely "unimportant" news, but I just wanted to mentioned that in theory there could arise a conflict of interests.

[BeckerWdf]

I am also unsure if the N&N entries is the right place to give the contributors some "fame". For that we have the acknowledgement pages. This page is a bit hidden I would say. Maybe we should link them in the N&N overview page...

[HannesWell]

I did not contribute to develop the multi-monitor-scaling. Only the SVG Feature.
Besides that I like the idea. :)

Adding on that for the sake of correctness if someone comes by: the monitor-specific scaling feature is primarily contributed by @akoch-yatta, @amartya4256, @ShahzaibIbrahim

Sorry if I got that wrong, but the current additions are just dummies to discuss/explore the result look. Eventually this PR will not add any such contributor information, just a template and the instructions, as written initially.

I think you were intending to use horizontal rulers (which show up correctly in GitHub) but this doesn't seem right when I render it by running jwebserver.

Yes exactly. Sorry that was a last minute change in the markdown syntax to create the horizontal line and using --- to create horizontal lines seems to have the potential to go wrong.

I have updated the PR and created the following screenshots how it could look:

Contributor mentioned after the headline and the bottom

Eventually only one will be used!
Click for full scale:

Contributor mentioned at the end

Click for full scale:

In the old format I would have suggested to list contributors on the left, but the layout is different now and I assume it's not easy and also not wanted to restore the old layout (or something similar):

Click for full scale:

Other answers in the next message.

[HannesWell]

Besides that I also really like the idea and would be in favor of adding the contributors right after the title line. That's also how many paper or online articles look like: the title is followed by a mentioned of the author before tha actual content.

That's also my favorite and as one can see also in the screenshots from my previous message adding the line at the bottom can also lead to many horizontal lines, which then looks bad IMHO.

Two primary question arise for me:

* _Optional vs. mandatory:_ should this mention be something optional? If yes, who decides if it is added? Not every N&N is contributed by the contributor of a feature, some of them "we" write on our own to make aware of a new feature. Should we then mention the contributors or not? Do we need their agreement on that?

In my opinion it should be optional and a decision of the contributor(s) if they/she/he want to be mentioned or not. As I tried to described in ide-wg/community#81 this should just enable the possibility to be mentioned and should be 'opt-in'. And if somebody writes a N&N on behalf of somebody else, consent should be obtained.

* _Correctness:_ we need to be even more thorough on checking the N&N in the future to ensure that the correct (and all) contributors are mentioned. If the contributor information in the news is not correct, it will do more harm than help. And this is not even easy. I above pointed to further people who have recently contributed to the monitor-specific scaling. But actually contributions to that (mentioned in according issues) go back some years with even further people having made contributions, so where to draw the line? Regarding that specific feature, the major contributors did dozens of PRs while others only did one, but should only the "primary" contributors be mentioned then? Maybe I am "too afraid" and such a long-running feature is rather seldom, but I would like to avoid that while giving some people more fame we also demotivate others if they stay unmentioned even though they have made contributions.

Initially I was hoping that this is a question that's not asked often, but it looks like we have a difficult case, right at the start.
In general I would say that it's the discretion of the N&N author to assemble the list of people involved. And while it's free text and the list of people can have arbitrary length, I think it should not become too long. Therefore I think it makes sense to focus only on the people that made significant contributions. But I think that doesn't depend on the number of PRs and in general could also be just contributions to a discussion. And in the text in general one could also be creative and say
contributed by ..., with support of .... or a like.
But again, I think the list should not be too long (what ever this means) and not every tiny bit of contribution has to be considered. But if we have a great feature where ten people contributed heavily, then so be it. As you mentioned scientific papers above, there the list of authors can also be long sometimes.
In the end, I think it's the responsibility of the creator of the PR to judge what's exactly suitable and what not. But I think we should write done some (weak) guidelines, that is evaluated over time.

In addition I am wondering whether this may influence for which feature news are written. News are supposed to be provided for the primary features of a release that consumers should know about (even though we don't have a precise definition when a feature has that "importance"). Adding the opportunity for mentioning the contributors in the news gives another, potentially conflicting incentive to writing the news, such that we may end up with rather unimportant news just to have a contributor mentioned. But to be honest, I don't see this as a risk as I also don't see that we will really get completely "unimportant" news, but I just wanted to mentioned that in theory there could arise a conflict of interests.

I agree that in theory that is possible, but for now I would trust the judgement of all committers to do 'the right things'. In the end a N&N goes trough the same review process as usual contributions and of course this possibility should not be misused. And if one disagrees, we have the usual ways of discussions and escalation chain, as like for other contributions too.
Furthermore I had the impression that writing N&N entries was not very appealing to all contributors (which might also be due to the fact that their creation was cumbersome in plain HTML) and some features/changes went unnoticed.
So if this increases the motivation to write N&N entries I think this would be good. But again it should not be missed-/overused and that should be assessed over time as well. But we are not the first one that do this, so I don't expect major problems.

I am also unsure if the N&N entries is the right place to give the contributors some "fame". For that we have the acknowledgement pages. This page is a bit hidden I would say. Maybe we should link them in the N&N overview page...

I considered the general acknowledgements as another, complementary story that I/we also wanted to work to make it more visible:

• https://gitlab.eclipse.org/eclipse-wg/ide-wg/community/-/issues/77

In the end, my proposal is to have both.

[vogella]

• Correctness: we need to be even more thorough on checking the N&N in the future to ensure that the correct (and all) contributors are mentioned. If the contributor information in the news is not correct, it will do more harm than help. And this is not even easy. I above pointed to further people who have recently contributed to the monitor-specific scaling. But actually contributions to that (mentioned in according issues) go back some years with even further people having made contributions, so where to draw the line? Regarding that specific feature, the major contributors did dozens of PRs while others only did one, but should only the "primary" contributors be mentioned then? Maybe I am "too afraid" and such a long-running feature is rather seldom, but I would like to avoid that while giving some people more fame we also demotivate others if they stay unmentioned even though they have made contributions.

I agree that this.

I think the list should not be too long (what ever this means) and not every tiny bit of contribution has to be considered. But if we have a great feature where ten people contributed heavily, then so be it. As you mentioned scientific papers above, there the list of authors can also be long sometimes.
In the end, I think it's the responsibility of the creator of the PR to judge what's exactly suitable and what not. But I think we should write done some (weak) guidelines, that is evaluated over time.

That definitely has a huge risk of creating harm, the judgement of if a contribution is "worthy of getting explicitly mentioned" has potential for a lot of work or of creating bad feelings. Also i can create a lot of effort during discussions.

Also please note that (at least my) clients are rarely aware of this existence of the N&N entries (before I educate them) so the audience of the documents is potentially relatively small. Do we have access numbers of these kind of documents?

I would prefer a more "failsafe" approach, like use the Git log for a release. For example for the platform news, just gather all contributors of the platform releases and list them in the N&N like: "This release was developed by....:" or something similar.

[HeikoKlare]

I would prefer a more "failsafe" approach, like use the Git log for a release. For example for the platform news, just gather all contributors of the platform releases and list them in the N&N like: "This release was developed by....:" or something similar.

I think we already have such a list out of which the acknowledgements are created.

We might of course think about more automation for the news-specific information, such as requiring an issue in the according repository for every feature that will have a news and linking all relevant PRs with that issue so that the contributors can be generated out of it. That might also allow to write a proper feature description from the beginning (which may frequently be updated) and then may be directly used for the news (since there are now in markdown now anyway).
But I am concerned that this would produce too much overhead and would add too much process on top of something that should be as lightweight as possible. So just consider this as a drop of thoughts and not as a proposal from my side.

[danthe1st]

I would prefer a more "failsafe" approach, like use the Git log for a release. For example for the platform news, just gather all contributors of the platform releases and list them in the N&N like: "This release was developed by....:" or something similar.

I personally like that idea, especially since that also shows smaller contributions. But I think the following should be considered:

• There are many repositories involved. I guess there needs to be a decision on contributions to which repositories should be included and where they should be included. Should only contributors from the eclipse-platform, eclipse-jdt and eclipse-pde be mentioned or also others? If others should be included, why? Or would this suggestion also apply to other projects that don't have the N&N entries on https://eclipse.dev/?
• Should new contributors be split from repeating/regular contributors?

[opcoach]

In my point of view, to keep it simple:

• Contributors (especially new ones) will always be proud to see their names in both N&N and acknowlegements or any other place.
• When the committer asks the contributor (if it's not himself) to write an N&N, he suggests adding the contributor's name (with a link to his github profile) and will remind the link to the 'How to write a N&N' documentation (repository, template to use, markdown, GitHub link, style, ... ). This documentation must be simple and straightforward.
• If there's a long history with many contributors, the template could mention them all but not display them all: e.g.: contributed by X and Y and others .... (and the 'others' could open or display the complete list in a tooltip). May be the template could have 2 fields : current contributors and historical contributors.
• As we will keep the news repository, it is always possible to review a N&N entry and adjust it before merging.

And ... I prefer when the names are shown after the title, but I also understand to write it below the description.

[HannesWell]

I would prefer a more "failsafe" approach, like use the Git log for a release. For example for the platform news, just gather all contributors of the platform releases and list them in the N&N like: "This release was developed by....:" or something similar.

First of all I want to state that we already have the acknowledgements that lists everyone who contributed at least one commit to a release and as mentioned in the end of #349 (comment), there is another effort to make that more visible and to enhance it (e.g. with a link to the GH profile):

• https://gitlab.eclipse.org/eclipse-wg/ide-wg/community/-/issues/77

And regarding Heiko's suggestion in #349 (comment): I share your concern that this is too complicated respectively impractical to use. I would also rather like to keep it simple.
To avoid frustration we just say that everyone who made code contributions should be added to the list, if desired. Most of the time the list should still be short enough and if it really becomes too long, the list could be collapsed?
Or alternatively, contributors could also just not be mentioned at all.
Naming the contributors should stay an optional possibility anyways.

*  Or would this suggestion also apply to other projects that don't have the N&N entries on https://eclipse.dev/?

The N&N in this repository only affect the Eclipse top level project and it's sub-projects, i.e. the repos in the eclipse-platform, eclipse-jdt, eclipse-equinox and eclipse-pde GH organizations. Other projects have their on release notes, but an aggregate is at

• https://eclipseide.org/release/noteworthy/

* Should new contributors be split from repeating/regular contributors?

Yes that's an idea we had for https://gitlab.eclipse.org/eclipse-wg/ide-wg/community/-/issues/77. If you have an opinion to that topic, please add a corresponding comment.

[HannesWell]

Since there seems a lot of interest in this topic I suggest to talk about it at the upcoming Dev-Call at Thursday:
https://github.com/eclipse-platform/eclipse.platform.releng.aggregator/wiki/Eclipse-IDE-%E2%80%90-Developers-Community-Call

In the meantime, I have started to create the intended basic template and added a section about the contributors list in the instruction. But all is work-in-progress and I'll apply the conclusion of this discussion.

[danthe1st]

Should new contributors be split from repeating/regular contributors?

Yes that's an idea we had for https://gitlab.eclipse.org/eclipse-wg/ide-wg/community/-/issues/77. If you have an opinion to that topic, please add a corresponding comment.

I think splitting that may be useful especially for the acknowledgement pages. For example (without changing much about it), it could look something like

We welcome the first contributions from [name](link), [name](link), ... and [name](link)
We also want to thank repeated contributions from ...

That being said, I think the current acknowledgement pages are just a wall of text. I think before making that more prominent, that page should be made more visually appealing and simpler to read/skim over. For example, one approach would be to add boxes (or use whatever UI elements may be useful) for the different types of contributions/teams. These could then be split in new and repeating contributions.
Also, when I used Google to find the acknowledgement pages, I only found this one which seems to not contain any of the formatting. I have no idea how one should find the correct page.

On the other side, that differentiation might be bit more difficult to do with the N&N pages so it might be better to not differentiate there.> > Should new contributors be split from repeating/regular contributors?

Yes that's an idea we had for https://gitlab.eclipse.org/eclipse-wg/ide-wg/community/-/issues/77. If you have an opinion to that topic, please add a corresponding comment.

I think splitting that may be useful especially for the acknowledgement pages. For example (without changing much about it), it could look something like

We welcome the first contributions from [name](link), [name](link), ... and [name](link)
We also want to thank repeated contributions from ...

That being said, I think the current acknowledgement pages are just a wall of text. I think before making that more prominent, that page should be made more visually appealing and simpler to read/skim over. For example, one approach would be to add boxes (or use whatever UI elements may be useful) for the different types of contributions/teams. These could then be split in new and repeating contributions.
Also, when I used Google to find the acknowledgement pages, the first result I found was this one which seems to not contain any of the formatting. I have no idea how one should find the correct page from the Eclipse site.

On the other side, that differentiation might be bit more difficult to do with the N&N pages so it might be better to not differentiate there.

[HannesWell]

Thanks for all your suggestions regarding the acknowledgements. All of them sounds very good and in fact that's close to what I'm currently working on as well. I'll create a PR as soon as it's in a state where we can discuss about and I'm happy to talk about the details. In the meantime, lets please keep this discussion focused on the N&N entries. If you want to discuss about enhancements of the acknowledgements now, lets move that to

• https://gitlab.eclipse.org/eclipse-wg/ide-wg/community/-/issues/77

[HannesWell]

After the discussion at last week's dev-call I have updated the instructions to include the discussed changes, mainly to change the instructions to consider all contributors, which contributed code.

Furthermore I have also into the suggestion to include profile pictures as well and tried out a few variants:

As far as I can tell it's not possible with markdown to make the picture round (like it's displayed in the GH profile).

In order to have a minimal level of recognizability the images have to be relatively large but then, at least in my impression, they become the 'highlight' of the page (at least if the entry itself doesn't contain images) and get a lot of attention.
Also some contributors have profile pictures (at least at GH) that show themself, which doesn't increase their recognition.
Besides that, the text can become ugly if multiple contributors are listed as one has to write a comma right after the picture or would have to use just and ... and ... and.
I'm therefore not in favor of adding it pictures, too. Although it could be nice to have. But I'm curious about your opinion.

[HannesWell]

This sentence is currently very vague, but I think we should restrict the link here and not allow arbitrary sites.
The GH profile or a linked-in profile would seems suitable to me, but already a link to a private website could be difficult as the page might change it's content in the future for various reasons and could contain content that's not serious and we don't want to link to.

So we could either introduce an allow-list or specify relatively precisely what's allowed and what's not.

[HannesWell]

In order to keep it simple, I think we should just allow GH profiles for now.
There one can easily and prominently add links to all other kind of profiles and personal websites and I hope that GH has more resources and possibilities to prevent abuse of that.

[danthe1st]

I think not including profile pictures is perfectly fine. One alternative would be to only include the images without the names but I guess not including profile pictures would be better.
Alternatively, it would be possible to include only profile pictures without the names but I guess it might be better to go with names only.
It would also be possible to use custom JS/CSS to detect the contributor list and apply custom formatting in some way (rounded images, repositioning the contributor list, etc).

Regarding the names, should there be a requirement on it being the name of the person or is mentioning usernames fine as well?

[HannesWell]

I think not including profile pictures is perfectly fine. One alternative would be to only include the images without the names but I guess not including profile pictures would be better.

I also think, only names are better.
With the old format we used in html I would have suggest to make the contributors a vertical list in the area I marked orange in the screenshot below. Then we could have the picture at the left and use the name as 'spacing' to the actual content:

But with markdown as we use it now the format is different, so I don't see that possibility for now.

It would also be possible to use custom JS/CSS to detect the contributor list and apply custom formatting in some way (rounded images, repositioning the contributor list, etc).

If that's possible I think it would be great. But that's above my skill level in the technologies you mentioned. But if you have more skills in JS/CSS I would be curious to see a PR. That enhances that. I was also wondering if one can further customize the output of marked-js used in the java-script part of the website?

Regarding the names, should there be a requirement on it being the name of the person or is mentioning usernames fine as well?

That's a good question I didn't thought about before. I personally would prefer real full names, just in the spirit of an open and transparent project, but I know that not everyone feels the same in that regard. At the moment I have updated the doc to just recommend to use full real names.

But on the other hand, keeping in mind that mentioning contributors is totally optional, I don't see currently why one wants to be mentioned as a contributor but at the same want's to stay anonymous? The goal is to give the people behind a change more visibility (if they want to), to give them 'fame' or 'advertise' them. But what would be benefit of doing it if just a pseudonym is used?
Therefore my suggestion is to require the real-name, if one wants to be mentioned.

[danthe1st]

If that's possibility I think it would be great. But that's above my skill level in the technologies you mentioned. But if you have more skills in JS/CSS I would be curious to see a PR. That enhances that. I was also wondering if one can further customize the output of marked-js used in the java-script part of the website?

I guess it might be sufficient to add one JS script to these pages without needing to customize the Markdown output (much) - but I don'tknow and I'mnot particularlygood at these things either. if necessary, this could probably be done retroactively so it wouldn't block this.

But what would be benefit of doing it if just a pseudonym is used?

People might use that pseudonym at many places online but not want it to be connected to their (full) real name. If they commonly use that pseudonym, they'd probably like to get recognised with that.

Also, what are your opinions on how regular contributors should be handled? I guess exactly the same as new contributors? Would they need to consent every time?

[HannesWell]

if necessary, this could probably be done retroactively so it wouldn't block this.

Yes, absolutely. That was also my plan.

But what would be benefit of doing it if just a pseudonym is used?

People might use that pseudonym at many places online but not want it to be connected to their (full) real name. If they commonly use that pseudonym, they'd probably like to get recognised with that.

Understand. What's the opinion of the others about that?

Also, what are your opinions on how regular contributors should be handled? I guess exactly the same as new contributors? Would they need to consent every time?

In general I would say yes, but at the same time I think one can assume that regular contributors who have been mentioned before are willing to be mentioned again. I think I would tag them in the PR that's adding the N&N entry and if they don't object, I'd assume they are fine.

[HeikoKlare]

Thank you for all the thorough considerations and discussion!
I agree with all recent proposals including the overall template and in particular:

• Allow pseudonyms (I also like the recommendation of using full names)
• Assume that regular contributors are fine with being mentioned again, tag them in the PR and give them chance to object

[merks]

I experimented with automatically "injecting" the avatar images. So given markdown like this:

Contributors:

• Eclipse Platform
• Hannes Wellmann
• Ed Merks

Contributors:

- [Eclipse Platform](https://github.com/eclipse-platform)
- [Hannes Wellmann](https://github.com/HannesWell)
- [Ed Merks](https://github.com/merks)

We could render it like this:

The renderer already visits all links to transform them correctly, so simply adding something that recognizes a reference to a GitHub organization and then inserting the HTML for the the profile image is very simple:

I wrote it this way so that just by appending a "#" or "?" to the URL one can disable the avatar insertion.

We just need a little bit of CCS to style it:

What do you think?

[danthe1st]

What do you think?

I think it looks great but that way of displaying it would probably take up too much space (at least if not collapsed). If there is a good way to add profile pictures without sacrificing much space, I would be all for it.

[merks]

Of course we can make them smaller; 24px is quite large. Of course at some point they get so small you can't recognize them.

20

18

16

[HeikoKlare]

I also like those embedded pictures! In the example, 20px looks fine to me as it's the largest size that does not seem to increase the line height (at least with the chosen font size). In general, I think having in-line pictures that do not or only slightly increase the line height is good.

[merks]

I’m happy to move forward with this when folks give the green light. Because it’s injected by the renderer, we can make adjustments as we see fit.

[danthe1st]

In my opinion , using Markdown lists (or whatever that's called) for the contributors takes a lot of space so it might be better to display them next to each other but I like the idea of just having normal Markdown links and inserting the profile pictures next to them. I hope this wouldn't cause issues with the GitHub API rate limits or similar but this looks fine with the code screenshot you shared.

I agree with looking into this further. @HannesWell what's your opinion on that?

Aside from that, are there other links to GitHub organisations in this repository where a ? or # should be appended?

[merks]

I did a search and found no org links (and even if there were, they'd probably look nice). That being said, of course there are other potential ways to make it conditional, e.g., that the f/file query parameter contains news/

So, the possibilities for rendering this are endless because we can detect that we rending avatars in a bulleted list and style that list differently, e.g., no bullets, not so much indentation, smaller line height, smaller font:

Note from the screen capture how easy it is to experiment with css changes in any browser with Ctrl-Shift-I.

So be creative and think about what you'd like to see most. E.g., if one put the list in a collapsible section, one could even generate/inject the avatars into the summary...

[danthe1st]

I really like how it works with a collapsible section that only shows the profile pictures by default. That would also be an elegant solution for the issue with too many people working on a feature.

[HannesWell]

Thanks @HeikoKlare for the fixes you mentioned, applied all of them

What do you think?

I like it very much. I was hoping that something like this would be possible and it looks great! Especially the fact that one does not have to manage the links to the profile twice is great.

I hope this wouldn't cause issues with the GitHub API rate limits or similar but this looks fine with the code screenshot you shared.

As this is rendered at the client any rate limit should be per viewer of the website. I think that's fine.

So, the possibilities for rendering this are endless because we can detect that we rending avatars in a bulleted list and style that list differently, e.g., no bullets, not so much indentation, smaller line height, smaller font:

No bullets sounds good as we already have the pictures which can be considered as 'bullets'. I also like the collapsible section.
But I haven't understood completely how this will look in the context of a full entry since as far as I understood you did some 'standalone' experiments. So depending on how we want it to look like the template has to be adjusted, hasn't it?

My suggestion is to finish this one without profile-pictures now and then you can create a follow-up PR on this where we can discuss and experiment with all the details about showing profile pictures.

So if there is anything that should be changed besides the pictures, please let me know soon.

[merks]

Maybe it's best to always make it collapsible so there is one consistent visual style?

<details>
<summary>Contributors</summary>

- [Hannes Wellmann](https://github.com/HannesWell)
</details>

This way we can also restrict the avatar rendering to happen only in an li in ul in a details...

[merks]

Here's how it looks:

I suppose the render can even render things different depending on the number of children.

In any case, style is always subject to being subjective. 😁

[HannesWell]

Maybe it's best to always make it collapsible so there is one consistent visual style?

After our private discussion and thinking about it more, I agree that this allows us to solve multiple problems:

• It simplifies subsequent injection of icons respectively makes it more robust as you suggested in:
  • Support rendering avatar pictures for links to profiles #358
• It makes the creation of the list itself more robust, as the extra lines can also go wrong as we saw in the beginning of this PR.
• It avoids potential 'visual confusion' as the separating horizontal line is already used when sections are separated.
• No need to change the style if the list of contributors becomes too long.

So I changed the template to use just the details pane.

I suppose the render can even render things different depending on the number of children.

Yes, I think it would be nice to unfold that section immediately if we only have one or two contributors. Because in general the contributors get more attention if they appear immediately (like with the previous approach), but if the list is too long, they would also get too much attention, since the main focus should still be on the content/change.
However, a collapsed section looks cleaner and with icons rendered the people already get some level of recognition.

[merks]

I guess this last point is still not resolved?

[HannesWell]

You mean the last sentence that suggests to use collapsed section when there are too many contributors?
Yes that's obsolete. Removed it.

[merks]

I guess this last point is still not resolved?

[HannesWell]

Thanks everyone for the discussion, it really enhanced the initial proposal.
I think this is now ready and all further discussion about the injection of icons should happen at

• Support rendering avatar pictures for links to profiles #358

[danthe1st]

@HannesWell I just tested it out and it seems necessary to add a line break before the enumeration of contributors.

For example

<details>
<summary>Contributors</summary>
- [Daniel Schmid](https://github.com/danthe1st)

</details>

<details>
<summary>Contributors</summary>

- [Daniel Schmid](https://github.com/danthe1st)

</details>

I think this might be something to address in the instructions since they include no empty line after the summary (both empty lines seem necessary). Can you check that?

(also the image from #358 does look very big on first sight for my preference even without hovering)

[HannesWell]

I think this might be something to address in the instructions since they include no empty line after the summary (both empty lines seem necessary). Can you check that?

For me only the first empty line, after the summary is necessary, and the template includes that already:
https://eclipse.dev/eclipse/markdown/?f=news/instructions.md#template

So, for me, it looks all correct.

(also the image from #358 does look very big on first sight for my preference even without hovering)

Yes, it's a trade-off, see also #358 (comment). I would say it's ok to have it larger in the expanded section as it's collapsed by default.
But if you think it should be changed, let's discuss the specific profile-picture issues in #358 or you can already create a PR with proposed enhancements and we discuss it there.

[danthe1st]

So, for me, it looks all correct.

My fault, seems like I confused myself

[merks]

I was surprised by the need but I noticed that even on a github hosted page that blank line is needed. Go figure.