Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 419363

Summary:	Are project description project.json and README.md redundant?
Product:	[ECD] Orion	Reporter:	Szymon Brandys <Szymon.Brandys>
Component:	Client	Assignee:	Project Inbox <orion.client-inbox>
Status:	RESOLVED WONTFIX	QA Contact:
Severity:	normal
Priority:	P3	CC:	antonm, ken_walker, malgorzata.tomczyk
Version:	4.0
Target Milestone:	---
Hardware:	PC
OS:	Windows 7
Whiteboard:

Description Szymon Brandys

2013-10-14 09:30:12 EDT

I think the description in project.json is redundant. We could just leave README.md and build basic description using it. Most of my projects have only one line description, so each time I want to modify it I have to keep in mind to modify both files.

Moreover README.md is a well know thing, once project.json is not. So other tools that may work with Orion projects will have easier life if all description is in one well known place.

One told me that GitHub does the same, has a basic desc + README.md, but frankly I do not use the basic desc there and just stick to README.md because it is shareable.

Comment 1 Malgorzata Janczarska

2013-10-14 10:12:00 EDT

We discussed this on one of the project calls and we wanted to have a Description that is a one line info about the project (just a hint what it is) apart from the README.md may be very detailed. Szymon suggested that Description should be shown based on README.md (fist few sentences of readme.md or some extra marks in the readme.md file), but I think that readme.md does not have to follow a standard in which it contains a short description in front. Users don't write readme.md having in mind that it will be displayed in Orion. As an example none of org.eclipse.orion.client, org.eclipse.orion.server, org.eclipse.orion.design follows this standard.

But I can agree that we don't really need the description field at all. If user has a project in his workspace he usually knows what it is, so most users will not use the description in Orion Project.

Comment 2 Szymon Brandys

2013-10-14 10:26:59 EDT

(In reply to Malgorzata Janczarska from comment #1)
> But I can agree that we don't really need the description field at all. If
> user has a project in his workspace he usually knows what it is, so most
> users will not use the description in Orion Project.

On the second thought...

This is how I see it. I have a project at eclipse.org, GitHub or some other Hub. I load it to my Orion workspace and what I would expect to see as its description is the description from Hub. And it should not change unless it is changed on Hub. So the description should rather be a link to the description, not an entry in project.json. And also the description should be available, only if the origin hub provides it.

Comment 3 Malgorzata Janczarska

2013-10-14 10:40:06 EDT

(In reply to Szymon Brandys from comment #2)
> And it should not change unless it
> is changed on Hub. So the description should rather be a link to the
> description, not an entry in project.json. And also the description should
> be available, only if the origin hub provides it.

Agreed, but I would then move the description to lower sections, plugin-specific, because each hub we host the project on may provide its own description, so we would avoid plugins racing over which should be responsible for providing link to the description.

Comment 4 John Arthorne

2015-05-05 14:48:09 EDT

Closing as part of a mass clean up of inactive bugs. Please reopen if this problem still occurs or is relevant to you. For more details see:

https://dev.eclipse.org/mhonarc/lists/orion-dev/msg03444.html