archives/freedoom
2
0
Fork 0
mirror of https://github.com/freedoom/freedoom.git synced 2025-09-01 13:25:46 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

README: revise "Submitting your work"

Browse source 
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.
This commit is contained in:
Mike Swanson 2014-11-04 22:01:10 -08:00
parent b1f15f2fcd
commit 6056ea3078
1 changed files with 52 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

62
README.adoc
View file

@ -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