In search of README for modules

classic Classic list List threaded Threaded
11 messages Options
Burke Mamlin Burke Mamlin
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

In search of README for modules

Devs,

Could we migrate toward a convention of using a README file at the root of each module?  I know there's a place for a description in the config.xml, but it's not very friendly when trying to scan through modules and understand their purpose.  And I'm sure an improved module repository will help some day, but not all modules make it into the module repository.

For example, adopt a convention of placing a README (e.g., one of README, README.txt, README.md) containing a description of the module in the root of each module's tree (or in trunk/ if the module uses the trunk/, branches/, tags/ folder convention).  This is already a prevailing convention in open source coding, right?

OpenMRS has a "readme.txt" file in trunk.  We could use the same for contribs.

Thoughts?

-Burke

[hidden email] from OpenMRS Developers' mailing list
Friedman, Roger (CDC/CGH/DGHA) (CTR) Friedman, Roger (CDC/CGH/DGHA) (CTR)
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: In search of README for modules

Burke --

    The OpenMRS README file only describes the project layout, it is not useful for understanding the purpose of OpenMRS.  What level of detail would you expect in the file, given that the most detailed information would be on the wiki?

 

From: [hidden email] [mailto:[hidden email]] On Behalf Of Burke Mamlin
Sent: Friday, May 18, 2012 10:59 AM
To: [hidden email]
Subject: [OPENMRS-DEV] In search of README for modules

 

Devs,

 

Could we migrate toward a convention of using a README file at the root of each module?  I know there's a place for a description in the config.xml, but it's not very friendly when trying to scan through modules and understand their purpose.  And I'm sure an improved module repository will help some day, but not all modules make it into the module repository.

 

For example, adopt a convention of placing a README (e.g., one of README, README.txt, README.md) containing a description of the module in the root of each module's tree (or in trunk/ if the module uses the trunk/, branches/, tags/ folder convention).  This is already a prevailing convention in open source coding, right?

 

OpenMRS has a "readme.txt" file in trunk.  We could use the same for contribs.

 

Thoughts?

 

-Burke


[hidden email] from OpenMRS Developers' mailing list

sunbiz sunbiz
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: In search of README for modules

In reply to this post by Burke Mamlin
I like the idea of README.md
Also it will be useful to have those for modules...

---
Regards,
Saptarshi PURKAYASTHA

My Tech Blog:  http://sunnytalkstech.blogspot.com
You Live by CHOICE, Not by CHANCE


On 18 May 2012 20:29, Burke Mamlin <[hidden email]> wrote:
Devs,

Could we migrate toward a convention of using a README file at the root of each module?  I know there's a place for a description in the config.xml, but it's not very friendly when trying to scan through modules and understand their purpose.  And I'm sure an improved module repository will help some day, but not all modules make it into the module repository.

For example, adopt a convention of placing a README (e.g., one of README, README.txt, README.md) containing a description of the module in the root of each module's tree (or in trunk/ if the module uses the trunk/, branches/, tags/ folder convention).  This is already a prevailing convention in open source coding, right?

OpenMRS has a "readme.txt" file in trunk.  We could use the same for contribs.

Thoughts?

-Burke


[hidden email] from OpenMRS Developers' mailing list
Burke Mamlin Burke Mamlin
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: In search of README for modules

In reply to this post by Friedman, Roger (CDC/CGH/DGHA) (CTR)
Roger, I was only referring to the fact that we've at least got something called readme.txt in trunk.  The fact that it's lowercase and only contains a description of the file structure is, how should I say, "room for improvement."  I did not mean in any way to suggest that the OpenMRS trunk/readme.txt would set our conventions.  I probably shouldn't have mentioned it.

Some better examples in our repository:
There are some examples on the web, Wordpress has a README template for plugins, etc.  As in the wikipedia article, it would be nice for a README to include a brief description (background/purpose for people who know nothing about the code), configuration/installation instructions, operation instructions, contact info, and (possibly) known bugs.  At this point, I'd just be happy if we just had a description.  A module ID is not enough to sufficiently describe most modules (or maybe I'm the only one who doesn't instantly recognize the meaning of DDU, CHIRDL, CHICA, AMRS, RKS, DHIS, DSS, I2B2, JSS, NBS, NCD, EMPI, PIXPDQ, RGRTA, and YANK among many others). :-)

I'm proposing that we promote using a README.txt file (git projects can use README.md) with  a simple template like:

== Description ==
This is the long description of this module/contribution.  No limit on size and you can use Markdown.  Replace this text with any background or description of your work that will help someone who knows nothing about your project understand what it is and its purpose.  When appropriate, direct people to where they can find more information.

== Installation ==
Describe how to install this work – e.g., for a module: requirements/configuration steps to compile, where to find the omod, and direction to use the OpenMRS module admin page to install the omod.  Most modules could use a standard template.  Contribs or special modules might have different instructions.

-Burke

On Fri, May 18, 2012 at 11:18 AM, Friedman, Roger (CDC/CGH/DGHA) (CTR) <[hidden email]> wrote:

Burke --

    The OpenMRS README file only describes the project layout, it is not useful for understanding the purpose of OpenMRS.  What level of detail would you expect in the file, given that the most detailed information would be on the wiki?

 

From: [hidden email] [mailto:[hidden email]] On Behalf Of Burke Mamlin
Sent: Friday, May 18, 2012 10:59 AM
To: [hidden email]
Subject: [OPENMRS-DEV] In search of README for modules

 

Devs,

 

Could we migrate toward a convention of using a README file at the root of each module?  I know there's a place for a description in the config.xml, but it's not very friendly when trying to scan through modules and understand their purpose.  And I'm sure an improved module repository will help some day, but not all modules make it into the module repository.

 

For example, adopt a convention of placing a README (e.g., one of README, README.txt, README.md) containing a description of the module in the root of each module's tree (or in trunk/ if the module uses the trunk/, branches/, tags/ folder convention).  This is already a prevailing convention in open source coding, right?

 

OpenMRS has a "readme.txt" file in trunk.  We could use the same for contribs.

 

Thoughts?

 

-Burke


[hidden email] from OpenMRS Developers' mailing list



[hidden email] from OpenMRS Developers' mailing list
Darius Jazayeri-2 Darius Jazayeri-2
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: In search of README for modules

I like the idea a lot. github pushes you to do this. We could look at the formats they support for guidance.

-Darius (by phone)

On May 18, 2012 10:02 AM, "Burke Mamlin" <[hidden email]> wrote:
Roger, I was only referring to the fact that we've at least got something called readme.txt in trunk.  The fact that it's lowercase and only contains a description of the file structure is, how should I say, "room for improvement."  I did not mean in any way to suggest that the OpenMRS trunk/readme.txt would set our conventions.  I probably shouldn't have mentioned it.

Some better examples in our repository:
There are some examples on the web, Wordpress has a README template for plugins, etc.  As in the wikipedia article, it would be nice for a README to include a brief description (background/purpose for people who know nothing about the code), configuration/installation instructions, operation instructions, contact info, and (possibly) known bugs.  At this point, I'd just be happy if we just had a description.  A module ID is not enough to sufficiently describe most modules (or maybe I'm the only one who doesn't instantly recognize the meaning of DDU, CHIRDL, CHICA, AMRS, RKS, DHIS, DSS, I2B2, JSS, NBS, NCD, EMPI, PIXPDQ, RGRTA, and YANK among many others). :-)

I'm proposing that we promote using a README.txt file (git projects can use README.md) with  a simple template like:

== Description ==
This is the long description of this module/contribution.  No limit on size and you can use Markdown.  Replace this text with any background or description of your work that will help someone who knows nothing about your project understand what it is and its purpose.  When appropriate, direct people to where they can find more information.

== Installation ==
Describe how to install this work – e.g., for a module: requirements/configuration steps to compile, where to find the omod, and direction to use the OpenMRS module admin page to install the omod.  Most modules could use a standard template.  Contribs or special modules might have different instructions.

-Burke

On Fri, May 18, 2012 at 11:18 AM, Friedman, Roger (CDC/CGH/DGHA) (CTR) <[hidden email]> wrote:

Burke --

    The OpenMRS README file only describes the project layout, it is not useful for understanding the purpose of OpenMRS.  What level of detail would you expect in the file, given that the most detailed information would be on the wiki?

 

From: [hidden email] [mailto:[hidden email]] On Behalf Of Burke Mamlin
Sent: Friday, May 18, 2012 10:59 AM
To: [hidden email]
Subject: [OPENMRS-DEV] In search of README for modules

 

Devs,

 

Could we migrate toward a convention of using a README file at the root of each module?  I know there's a place for a description in the config.xml, but it's not very friendly when trying to scan through modules and understand their purpose.  And I'm sure an improved module repository will help some day, but not all modules make it into the module repository.

 

For example, adopt a convention of placing a README (e.g., one of README, README.txt, README.md) containing a description of the module in the root of each module's tree (or in trunk/ if the module uses the trunk/, branches/, tags/ folder convention).  This is already a prevailing convention in open source coding, right?

 

OpenMRS has a "readme.txt" file in trunk.  We could use the same for contribs.

 

Thoughts?

 

-Burke


[hidden email] from OpenMRS Developers' mailing list



[hidden email] from OpenMRS Developers' mailing list

[hidden email] from OpenMRS Developers' mailing list
Michael Downey Michael Downey
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: In search of README for modules

There has been an pretty good README file (if I say so myself) in the
Standalone distribution since we started putting it out. Perhaps we
could look at that for ideas?

Michael

_________________________________________

To unsubscribe from OpenMRS Developers' mailing list, send an e-mail to [hidden email] with "SIGNOFF openmrs-devel-l" in the  body (not the subject) of your e-mail.

[mailto:[hidden email]?body=SIGNOFF%20openmrs-devel-l]
Burke Mamlin Burke Mamlin
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: In search of README for modules

In reply to this post by Darius Jazayeri-2
Exactly.  On github, the very first step after creating a repo is to commit the README file.[1]

While a README isn’t a required part of a GitHub repo, it is a good idea to have one. READMEs are a great place to describe your project or add some documentation such as how to install or use your project.

The github/markup project is what github uses for handling README files.  I'd propose we start by supporting README & README.txt as plain text files and, possibly, README.md and README.markdown as markdown syntax.  My only near-term hope would be to start migrating toward the common practice of including a README file with a brief description.

I've proposed a README convention on the Module Conventions page and created TRUNK-3376 as a task to get a sample README.txt file into the basicmodule archetype.

Cheers,

-Burke

[1] http://help.github.com/create-a-repo/

On Fri, May 18, 2012 at 2:24 PM, Darius Jazayeri <[hidden email]> wrote:

I like the idea a lot. github pushes you to do this. We could look at the formats they support for guidance.

-Darius (by phone)

On May 18, 2012 10:02 AM, "Burke Mamlin" <[hidden email]> wrote:
Roger, I was only referring to the fact that we've at least got something called readme.txt in trunk.  The fact that it's lowercase and only contains a description of the file structure is, how should I say, "room for improvement."  I did not mean in any way to suggest that the OpenMRS trunk/readme.txt would set our conventions.  I probably shouldn't have mentioned it.

Some better examples in our repository:
There are some examples on the web, Wordpress has a README template for plugins, etc.  As in the wikipedia article, it would be nice for a README to include a brief description (background/purpose for people who know nothing about the code), configuration/installation instructions, operation instructions, contact info, and (possibly) known bugs.  At this point, I'd just be happy if we just had a description.  A module ID is not enough to sufficiently describe most modules (or maybe I'm the only one who doesn't instantly recognize the meaning of DDU, CHIRDL, CHICA, AMRS, RKS, DHIS, DSS, I2B2, JSS, NBS, NCD, EMPI, PIXPDQ, RGRTA, and YANK among many others). :-)

I'm proposing that we promote using a README.txt file (git projects can use README.md) with  a simple template like:

== Description ==
This is the long description of this module/contribution.  No limit on size and you can use Markdown.  Replace this text with any background or description of your work that will help someone who knows nothing about your project understand what it is and its purpose.  When appropriate, direct people to where they can find more information.

== Installation ==
Describe how to install this work – e.g., for a module: requirements/configuration steps to compile, where to find the omod, and direction to use the OpenMRS module admin page to install the omod.  Most modules could use a standard template.  Contribs or special modules might have different instructions.

-Burke

On Fri, May 18, 2012 at 11:18 AM, Friedman, Roger (CDC/CGH/DGHA) (CTR) <[hidden email]> wrote:

Burke --

    The OpenMRS README file only describes the project layout, it is not useful for understanding the purpose of OpenMRS.  What level of detail would you expect in the file, given that the most detailed information would be on the wiki?

 

From: [hidden email] [mailto:[hidden email]] On Behalf Of Burke Mamlin
Sent: Friday, May 18, 2012 10:59 AM
To: [hidden email]
Subject: [OPENMRS-DEV] In search of README for modules

 

Devs,

 

Could we migrate toward a convention of using a README file at the root of each module?  I know there's a place for a description in the config.xml, but it's not very friendly when trying to scan through modules and understand their purpose.  And I'm sure an improved module repository will help some day, but not all modules make it into the module repository.

 

For example, adopt a convention of placing a README (e.g., one of README, README.txt, README.md) containing a description of the module in the root of each module's tree (or in trunk/ if the module uses the trunk/, branches/, tags/ folder convention).  This is already a prevailing convention in open source coding, right?

 

OpenMRS has a "readme.txt" file in trunk.  We could use the same for contribs.

 

Thoughts?

 

-Burke


[hidden email] from OpenMRS Developers' mailing list



[hidden email] from OpenMRS Developers' mailing list

[hidden email] from OpenMRS Developers' mailing list


[hidden email] from OpenMRS Developers' mailing list
Darius Jazayeri-2 Darius Jazayeri-2
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: In search of README for modules

In reply to this post by Michael Downey

Someone at a real keyboard should create a ticket in emma (archetype) to automatically create a readme.txt with the could've description.

-Darius (by phone)

On May 18, 2012 11:42 AM, "Michael Downey" <[hidden email]> wrote:
There has been an pretty good README file (if I say so myself) in the
Standalone distribution since we started putting it out. Perhaps we
could look at that for ideas?

Michael

_________________________________________

To unsubscribe from OpenMRS Developers' mailing list, send an e-mail to [hidden email] with "SIGNOFF openmrs-devel-l" in the  body (not the subject) of your e-mail.

[mailto:[hidden email]?body=SIGNOFF%20openmrs-devel-l]

[hidden email] from OpenMRS Developers' mailing list
Darius Jazayeri-2 Darius Jazayeri-2
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: In search of README for modules

Module's description. Silly phone.

-Darius (by phone)

On May 18, 2012 12:51 PM, "Darius Jazayeri" <[hidden email]> wrote:

Someone at a real keyboard should create a ticket in emma (archetype) to automatically create a readme.txt with the could've description.

-Darius (by phone)

On May 18, 2012 11:42 AM, "Michael Downey" <[hidden email]> wrote:
There has been an pretty good README file (if I say so myself) in the
Standalone distribution since we started putting it out. Perhaps we
could look at that for ideas?

Michael

_________________________________________

To unsubscribe from OpenMRS Developers' mailing list, send an e-mail to [hidden email] with "SIGNOFF openmrs-devel-l" in the  body (not the subject) of your e-mail.

[mailto:[hidden email]?body=SIGNOFF%20openmrs-devel-l]

[hidden email] from OpenMRS Developers' mailing list
Michael Downey Michael Downey
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: In search of README for modules

Hi,

On Fri, May 18, 2012 at 3:51 PM, Darius Jazayeri <[hidden email]> wrote:
> Module's description. Silly phone.
>
> On May 18, 2012 12:51 PM, "Darius Jazayeri" <[hidden email]> wrote:
>>
>> Someone at a real keyboard should create a ticket in emma (archetype) to
>> automatically create a readme.txt with the could've description.

https://tickets.openmrs.org/browse/EMMA-28

Michael

_________________________________________

To unsubscribe from OpenMRS Developers' mailing list, send an e-mail to [hidden email] with "SIGNOFF openmrs-devel-l" in the  body (not the subject) of your e-mail.

[mailto:[hidden email]?body=SIGNOFF%20openmrs-devel-l]
Burke Mamlin Burke Mamlin
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: In search of README for modules

In reply to this post by Darius Jazayeri-2
Done.  EMM-27

On Fri, May 18, 2012 at 3:51 PM, Darius Jazayeri <[hidden email]> wrote:

Module's description. Silly phone.

-Darius (by phone)

On May 18, 2012 12:51 PM, "Darius Jazayeri" <[hidden email]> wrote:

Someone at a real keyboard should create a ticket in emma (archetype) to automatically create a readme.txt with the could've description.

-Darius (by phone)

On May 18, 2012 11:42 AM, "Michael Downey" <[hidden email]> wrote:
There has been an pretty good README file (if I say so myself) in the
Standalone distribution since we started putting it out. Perhaps we
could look at that for ideas?

Michael

_________________________________________

To unsubscribe from OpenMRS Developers' mailing list, send an e-mail to [hidden email] with "SIGNOFF openmrs-devel-l" in the  body (not the subject) of your e-mail.

[mailto:[hidden email]?body=SIGNOFF%20openmrs-devel-l]

[hidden email] from OpenMRS Developers' mailing list


[hidden email] from OpenMRS Developers' mailing list
Loading...