search

cckec / winetricks

Automatically exported from code.google.com/p/winetricks
0 stars 0 forks source link

SVN 220: Add README file to lbriefly describe project, contact, bugs, dependencies #5

Closed GoogleCodeExporter closed 8 years ago

GoogleCodeExporter commented 8 years ago 
It would be nice if the project had a README that would list the project in a 
concise manner:

   DESCRIPTION

   <in a paragraph or two describe the project and script>

   DEPENDENCIES

   <list dependencies on external programs, like wget ...>

   CONTACT

   <List primary contact email address etc.>

Original issue reported on code.google.com by jari.aalto.fi@gmail.com on 5 Mar 2011 at 12:13

GoogleCodeExporter commented 8 years ago 
I've added a nicer paragraph or two at the top of the file to
take care of this.

(The project is constrained to have most of its info in a single
file, the main shell script, because of the way I intend users to
download and run it without installation.)

Original comment by daniel.r...@gmail.com on 5 Mar 2011 at 4:17

GoogleCodeExporter commented 8 years ago 

The GNU project recommends that every software project includes files:
NEWS, README, AUTHORS, COPYING and ChangeLog.

This may not seem a big issue at start, but as soon as the project is
picked for a Linux distribution, the lack of proper files make the
packhing word harder when they deviate or don't have uniform
structure. The use of standard files help other people (packagers) to
evaluate, reviews and manage projects in semi-automated manner when
they use a uniform structure.

This project is currently entering the Debian repository (packaged by
me) This will make the program available for tens of thousands users.

The ssftware is installed under /usr/bin so any documentation that are
placed inside the comments of the programs:

*) Won't be read by the users
*) Will be hard to parse automatically
*) Standard place for documentation is /usr/share/doc/<package> and
   currently there is no NEWS, README, AUTHORS, COPYING and ChangeLog
   to follow the progress of the project.

Please coniser separating the documentation to those files to help
packaging now and future versions.

These files also help other Linux distributions, like Fedora (rpm),
BSD, or SUSE that may decide to package the software for the large
user base.

For more information, see:

  Summary of "ChangeLog" file
  http://www.delicious.com/jariaalto/gnu+changelog+my

  The NEWS etc files explained.
  http://sourceware.org/autobook/autobook/autobook_25.html

  Why file COPYING must be in the project
  http://www.gnu.org/licenses/gpl-faq.html#WhyMustIInclude

Excerpts:

`NEWS'

    A record of user-visible changes to a package. The format is not
    strict, but the changes to the most recent version should appear
    at the top of the file.

`README'

    The first place a user will look to get an overview for the
    purpose of a package, and perhaps special installation
    instructions.

`AUTHORS'

    Lists the names, and usually mail addresses, of individuals who
    worked on the package.

`ChangeLog'

    The ChangeLog is an important file--it records the changes that
    are made to a package. The format of this file is quite strict
    (see section 5.5 Documentation and ChangeLogs).

Original comment by jari.aalto.fi@gmail.com on 6 Mar 2011 at 11:15