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 <https://github.com/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<https://wiki.openmrs.org/x/WgBLAQ>page and created TRUNK-3376 <https://tickets.openmrs.org/browse/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 <[email protected]>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" <[email protected]> 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: >> >> - >> openmrs-contrib/csv-concept-importer/trunk/<http://svn.openmrs.org/openmrs-contrib/csv-concept-importer/trunk/> >> - >> openmrs-contrib/reports/<http://svn.openmrs.org/openmrs-contrib/reports/> >> - >> openmrs-contrib/sdmx-hd-parser/README.txt<http://svn.openmrs.org/openmrs-contrib/sdmx-hd-parser/README.txt> >> >> There are some >> examples<https://www.cs.washington.edu/education/courses/326/02wi/homework/hw5/good-readmes.html> >> on >> the web, Wordpress has a README >> template<http://wordpress.org/extend/plugins/about/readme.txt> for >> plugins, etc. As in the wikipedia >> article<http://en.wikipedia.org/wiki/README>, >> 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) < >> [email protected]> 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:* [email protected] [mailto:[email protected]] *On Behalf Of *Burke >>> Mamlin >>> *Sent:* Friday, May 18, 2012 10:59 AM >>> *To:* [email protected] >>> *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 <http://svn.openmrs.org/openmrs-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**** >>> ------------------------------ >>> >>> Click here to >>> unsubscribe<[email protected]?body=SIGNOFF%20openmrs-devel-l>from >>> OpenMRS Developers' mailing list >>> **** >>> >> >> ------------------------------ >> Click here to >> unsubscribe<[email protected]?body=SIGNOFF%20openmrs-devel-l>from >> OpenMRS Developers' mailing list > > ------------------------------ > Click here to > unsubscribe<[email protected]?body=SIGNOFF%20openmrs-devel-l>from > OpenMRS Developers' mailing list > _________________________________________ To unsubscribe from OpenMRS Developers' mailing list, send an e-mail to [email protected] with "SIGNOFF openmrs-devel-l" in the body (not the subject) of your e-mail. [mailto:[email protected]?body=SIGNOFF%20openmrs-devel-l]
