--------------------------
Scoop 0.9 development
How to contribute
--------------------------

As with any open source project, there are several ways to contribute to Scoop.
This document outlines some of things that you can do to make Scoop better, and
how to contribute that work.

While reading this, keep in mind that Scoop is not a massive project with
strict rules on contributing. Nearly any contribution is appreciated, and most
are accepted. Discussion is an important part of improving Scoop, so feel free
to discuss your ideas with other on the scoop-dev mailing list,
scoop.kuro5hin.org, or in #scoop.


-------------
Documentation
-------------

Nearly any project could stand to have better documentation, and Scoop is
certainly no exception. If you'd like to write and/or maintain some parts of
the docs, we'll love you forever.

Docs aren't completely missing, but they're lacking. The Scoop Admin Guide,
which is located in the doc/ directory, holds most of Scoop's docs. It's
maintained in LyX format (http://www.lyx.org/) and the HTML is generated from
that.

The easiest way to contribute to docs is to read through them and point out
problems on the scoop-help mailing list. Knowing about deficiencies in the docs
is the first step in getting them improved. If you see a missing or out-dated
section, a confusing paragraph, or even a mis-spelled word, let someone know,
and it will hopefully be corrected.

Of course, we would prefer if you fixed it yourself and sent in a patch. Make
any changes you think are necessary, then make a patch and send it in (see the
'Sending a Patch' section later in this document). In the case of the Scoop
Admin Guide, make your changes to the LyX file and make the patch against it.
Someone else will re-generate the HTML once the patch is accepted.

If you're documenting a certain part of Scoop and realize you don't fully
understand it, email scoop-help and ask for an explanation. Someone will be
able to provide you with a few semi-coherent paragraphs, which you can
(hopefully) translate into understandable and useful docs.

Remember, blessed are the doc writers.


------------------------------
Bug Reports & Feature Requests
------------------------------

While using Scoop, more than likely, you'll come across something that doesn't
work quite the way it should, or decide that Scoop needs to do something that
it doesn't. In this case, you should send your bug report or feature request
to the scoop-help mailing list, or to the Scoop web site.

You might also try submitting to the appropriate queue on Scoop's Request
Tracker (http://scoop.kuro5hin.org/rt/). Login with username 'guest' and
password 'guest', then create a new ticket in the appropriate queue.

In any case, please try and give as much as information as possible. For a bug,
tell what you consider the bug to be, where you found it, and the steps
necessary to re-produce it. For feature requests, make sure to include a clear,
through description of what you think should be added. In either case, make
sure there is a way for the developers to contact you, in case more information 
is necessary.

Bug reports and feature requests are always appreciated, but if you've got the
knowledge, patches that fix bugs or implement features are always preferred.

----
Code
----

It's almost always easier for a developer to apply a patch than it is to write
the code themselves. Because of this, code patches that fix bugs or add
features help developers to get a little more sleep at night. But before you
send in your code, there are some guidelines to follow.

Before you start on a major feature, or possibly even a minor one, it would be
a good idea to email scoop-dev and make sure that no one is already working on
the same feature, and to make sure that the developers think the feature is
worth working on (you wouldn't want to write a major feature in only to have it
rejected completely). Also, by doing this, you can discuss your idea with
others and possibly improve on it.

Most importantly, make sure that your patch is against the most recent CVS
version of Scoop, not a released version. Just before sending your patch in for
review, use CVS to update your local copy of Scoop and run some basic tests one
more time, just to be sure. Some minor problems are okay, they can be
corrected. However, patches against an older version, such as .8.1, will be
rejected.

Also, do your best to follow the coding style used within Scoop. It's not (yet)
documented anywhere, so look over some of the existing code to get a feel for
it. Because of the coding style's undocumented status, patches usually aren't
rejected based on style.

If your patch requires any changes to the database, then be sure to include a
database patch. There are plenty of examples of these in the
struct/patch-files/current/ directory, so look there for an idea of how to make
one. Also update the README file in that directory with a description of your
patch. It would also be nice to re-generate the scoop.sql file. To do that,
create a fresh scoop database, apply your patch, then dump the new SQL back
out:

 (this first step might not be necessary for you)
$ mysqladmin -u<user> -p<pass> drop <db>
$ mysqladmin -u<user> -p<pass> create <db>
$ mysql -u<user> -p<pass> <db> < struct/scoop.sql
$ mysql -u<user> -p<pass> <db> < struct/patch-files/current/patch-foo.sql
$ mysqldump -u<user> -p<pass> <db> > struct/scoop.sql

In the base Scoop directory, update the appropriate part of the CHANGES file to
reflect you addition or change. Also, if it's your first time contributing to
Scoop, add a line to the end of the CREDITS file.

Once you're ready to make your patch, be sure to follow the instructions in the
'Sending a Patch' section of this document. If your patch isn't in the proper
format, or doesn't include all the necessary parts, then it won't be accepted.


---------------
Sending a Patch
---------------

Before sending a patch in, you have to actually make it. Use the 'cvs diff'
command for this:

$ cvs diff -c [files] > patch.diff

The 'cvs diff' part runs the cvs program and tells it to compare the files on
your computer with the ones on the server, then generate a file with the
differences between the two.

The '-c' option makes a context diff instead of a unified diff. Be sure to use
this, otherwise it is much more difficult for developers to review your patch.

A list of files is optional. If not given, CVS will go through each directory
under, and including, the current one and compare the files within them. If a
list of files is given, then only those are compared.

Finally, CVS sends its output to stdout, so must redirect it to a file to save
it. Replace 'patch.diff' with whatever you want to name the patch, though keep
the .diff extension.

If you'd like, you can also compress your patch, with gzip or bzip2, though it
is completely optional. It makes no difference to the developers.

Once you have your patch ready, you may want to put it up for commenting. If
so, send it to the scoop-dev mailing list, with an explanation of it and a
request for comments. Do not put your patch in-line with the rest of the
message; you must attach it. If you do not, then line wrapping will most likely
break the patch.

When you think your patch is ready to be reviewed, send it to
patches@scoop.kuro5hin.org. The same rules for attaching the patch apply.

Once you've submitted a patch, be patient. Developers have a lot to do, both
within and outside of Scoop, so you're patch might not be reviewed right away.
Whoever is reviewing your patch will probably contact you about it, if only to
say that's it been applied. If you don't receive anything regarding your patch
after a week or so, you could try sending another email to see what its status
is. There are several factors that could contribute to your patch not being
reviewed right away, but a patch is never flat-out ignored.

It's possible that your patch will be rejected, but don't be discouraged by
this. Whoever rejects your patch will do their best to explain why they did so,
and to offer advice on what would make the patch better. Follow the advice and
there's a good chance your patch will be accepted.
