README: revise "Submitting your work"
Git is not within the reach of most contributors, so let's de-emphasize its importance. It would be nice if more people submitted things via pull requests, but it's a fact-of-life for Freedoom committing to be done by more technically-minded people (typically its maintainers). Point instead to the forums, issue tracker, and file sharing sites as the common and accepted means of submitting work.master
parent
b1f15f2fcd
commit
6056ea3078
62
README.adoc
62
README.adoc
|
@ -179,17 +179,59 @@ patches, but keep in mind:
|
|||
|
||||
=== Submitting your work
|
||||
|
||||
TODO: Figure out the best method of doing this. This mainly requires
|
||||
time to see what works best.
|
||||
The most common, and a fairly simple method, to submit your work is by
|
||||
posting it on the http://www.doomworld.com/vb/freedoom/[Freedoom
|
||||
forum] on Doomworld Forums. This allows a great number of people to
|
||||
review the contribution and provide feedback, although the
|
||||
registration process is known to be cumbersome.
|
||||
|
||||
If you use git, make sure your commit messages start with a single
|
||||
line, under 72 characters, which provides an adequate summary of your
|
||||
changes. You should prefix this line with the component you are commit
|
||||
(for example, ``map17: fixed unbeatable map''). This should be
|
||||
followed by a blank line and more explanation if it's needed (for
|
||||
example, explaining what part of the map was broken). The commit
|
||||
`2013-12-20T16:06:55Z!rjy@users.sourceforge.net` shows a good example
|
||||
of a well-structured commit message.
|
||||
An alternative to using the forum, is to post your submission on the
|
||||
https://github.com/freedoom/freedoom/issues[issue tracker], which may
|
||||
also be peer-reviewed and provide a feedback cycle.
|
||||
|
||||
Lastly, it is possible to get work submitted by joining the official
|
||||
irc://irc.oftc.net/freedoom[#freedoom] IRC channel, although this
|
||||
poses the greatest risk of being lost in the scrollback history and
|
||||
forgotten.
|
||||
|
||||
Unfortunately, the Freedoom project cannot provide hosting space in
|
||||
the form of a web page nor FTP, however there are many free file hosts
|
||||
to use when you need a location to upload files. Sites and services
|
||||
such as https://www.dropbox.com/[Dropbox] and
|
||||
https://mega.co.nz/[Mega], as well as others, are common and should be
|
||||
simple to use.
|
||||
|
||||
==== Using Git
|
||||
|
||||
You can also use commit directly off of a clone of the Freedoom
|
||||
repository, although this tends to be a highly technical task and it
|
||||
is okay to allow other Freedoom maintainers to do it instead: that is
|
||||
our normal mode of operation! Pull requests may come from anywhere,
|
||||
you need not use GitHub if you wish not to, however GitHub usually
|
||||
makes this sort of thing very simple.
|
||||
|
||||
Freedoom uses the commit message format commonly seen in distributed
|
||||
version control systems, and adopted by high-profile projects such as
|
||||
Linux and Git. The first line of a message needs to be a short
|
||||
summary, preferably at a 72-character limit. The summary usually
|
||||
begins with a short component name followed by a colon, this can be a
|
||||
directory name (eg, `musics:`), a resource name (eg, `map17:`), or a
|
||||
more generic component (eg, `build system:`). The summary line should
|
||||
never bleed into a second line, and should never be the start of a
|
||||
lengthy explanation. If the commit needs further explanation (and
|
||||
they often do), use extra paragraphs and write in plain-English what
|
||||
the commit is about. The commit
|
||||
`2014-08-24T22:42:37Z!fraggle@gmail.com` is a good example.
|
||||
|
||||
Additionally, use either simple pointers to other commits, such as
|
||||
``my previous commit'', or use http://esr.ibiblio.org/?p=3872[action
|
||||
stamps], which can improve the meaningfulness of commit identifiers if
|
||||
the repository is rewritten at an early point in, or if the repository
|
||||
is ever converted to another DVCS. At the time of writing (November
|
||||
2014), core Git does not yet have a mechanism to output this format,
|
||||
but you may use a
|
||||
https://gist.github.com/chungy/195f53bfb9253584e596[shell script] and
|
||||
place it in your `$PATH` to achieve some ease in doing them.
|
||||
|
||||
You should commit often; each important change should get its own
|
||||
commit, but minor changes need not. Take advantage of git's ability to
|
||||
|
|
Loading…
Reference in New Issue