Bug 531141

Summary:	Include Howto Contribute in the Source Code
Product:	[Eclipse Project] Platform	Reporter:	Patrik Suzzi <psuzzi>
Component:	UI	Assignee:	Platform-UI-Inbox <Platform-UI-Inbox>
Status:	NEW ---	QA Contact:
Severity:	enhancement
Priority:	P3	CC:	Lars.Vogel, mistria
Version:	4.8
Target Milestone:	---
Hardware:	All
OS:	All
Whiteboard:

Description Patrik Suzzi

2018-02-14 06:22:29 EST

As pointed by Mickael in Bug 531089 comment 4, we should ship the how to contribute Guide in the source code. 

However, wiki is accessible from web and supports image and formatting.

Here is a more general idea: 

- create a /doc project in the Platform working tree
- put there documentation: asciidoc, markdown, etc.
- point the README.md to the index of that documentation
- add a (/doc/pom.xml) mvn build that generate static html doc
- point the wiki to the generated index, i.e. http://git.eclipse.org/c/platform/eclipse.platform.ui.git/plain/doc/index.html

Comment 1 Mickael Istria

2018-02-14 06:29:36 EST

I would consider the generation of HTML as a "nice-to-have" and the copy HTML to wiki as a dangerous choice as it involves more work and risks of being out-of-date. Linking is more sustainable. We can link to the GitHub mirror if we want rendered output.

Comment 2 Lars Vogel

2018-02-14 06:32:05 EST

+1 for plain text (Markdown) instead of rich text.

Comment 3 Patrik Suzzi

2018-02-14 16:10:12 EST

Note: we have multiple projects sharing the same information on how to contribute. 

For example: eclipse.platform.ui and eclipse.platform.runtime are referring the same wiki page http://wiki.eclipse.org/Platform_UI/How_to_Contribute

To keep plain text docs in a project without duplication, we should:

- in eclipse.platform.ui/README.md -> link to docs/README.md
- in eclipse.platform.runtime/README.md -> link to ../eclipse.platform.ui/doc/README.md
- in eclipse.platform.ui/docs/README.md : keep the main contribution guide.

Having a website would be beneficial for the users who have not (yet) cloned both projects. 

If we don't generate a static html website, I'd like to keep also the link to the Eclipse Wiki how to contribute.