Bug 402365 - Add a README.MD at the root of the Git repository
Summary: Add a README.MD at the root of the Git repository
Status: RESOLVED FIXED
Alias: None
Product: Mihini
Classification: IoT
Component: Agent (show other bugs)
Version: unspecified   Edit
Hardware: PC Mac OS X
: P3 normal (vote)
Target Milestone: 0.9 M1   Edit
Assignee: Project Inbox CLA
QA Contact:
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2013-03-04 13:40 EST by Benjamin Cabé CLA
Modified: 2013-05-22 10:57 EDT (History)
4 users (show)

See Also:

Attachments
0001-Adding-a-README.md-at-the-root-of-the-repository-to-.patch (7.13 KB, patch)
2013-03-12 11:46 EDT, Romain Perier CLA 		no flags Details | Diff
0002-Adding-a-README.md-at-the-root-of-the-repository-to-.patch (7.23 KB, patch)
2013-03-13 10:37 EDT, Romain Perier CLA 		no flags Details | Diff
Show Obsolete (1) View All Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Benjamin Cabé CLA 2013-03-04 13:40:19 EST 
Would be good to add a README.MD at the root of the repository to give basic instructions and/or pointers to the wiki for explaining how to build, etc.

Also, this README should clarify what is contained in the 'non-free' git submodule.
Comment 1 Romain Perier CLA 2013-03-12 11:46:00 EDT 
I have wrote a README.md explaining basic steps to build, start and interact with the Mihini Agent. You can find the patch in attachment (produced by git format-patch).
Comment 2 Romain Perier CLA 2013-03-12 11:46:41 EDT 
Created attachment 228275 [details]
0001-Adding-a-README.md-at-the-root-of-the-repository-to-.patch
Comment 3 Romain Perier CLA 2013-03-12 11:47:32 EDT 
You can see the result at https://github.com/rperier/mihini-markdown-doc/blob/master/README.md
Comment 4 Benjamin Cabé CLA 2013-03-12 14:00:10 EDT 
This is great!
I wonder if this is redundant with http://wiki.eclipse.org/Mihini/Mihini_Agent_Linux_build_instructions ?
Should the README be very short, and point to the wiki page for getting more details?
I think the wiki is more appropriate for "detailed" content in that anyone can very easily contribute, even it's just for fixing a small typo.
WDYT?
Comment 5 Romain Perier CLA 2013-03-13 05:44:28 EDT 
According to the Mihini team, that's important to have these kind of instructions in the repository. Well, we could at least explain how to build the agent, how to start it and then point the wiki page to get more details. What do you think ?
Comment 6 Cuero Bugot CLA 2013-03-13 07:00:49 EDT 
Hi Benjamin,

Thx for the feedback. We decided to put all documentation that is tightly coupled to the source code WITH the source code (described as 'file based' documentation in the eclipse process).
This will help ensure have the doc and code in sync.
The major downside of that approach is that it will be harder for non committer to change the doc, but we plan to explain that process (maybe leveraging github online edit or another wiki interface) so that to lower the newcomer entry barrier.

In the meantime you are right, the wiki build instruction will reference the git file.
Comment 7 Romain Perier CLA 2013-03-13 10:37:14 EDT 
Hi,

See a new patch in attachement, it fixes some grammar issues.
Also, I have updated the wiki page. So please commit these changes quickly
Comment 8 Romain Perier CLA 2013-03-13 10:37:52 EDT 
Created attachment 228351 [details]
0002-Adding-a-README.md-at-the-root-of-the-repository-to-.patch
Comment 9 Laurent Barthelemy CLA 2013-03-13 12:35:59 EDT 
README.md made by Romain was pushed in org.eclipse.mihini.git: 

cb3c2b7c3050d381478c87a636fc0c5e051e0952: Adding a README.md at the root of the repository to give basic instructions explaining how to build and start the agent. It fixes bug #402365.