@@ -8,24 +8,25 @@ Free Software project.
## Who Is In Charge?
Currently, [Bradley M. Kuhn](http://ebb.org/bkuhn/) is the editor-in-chief of
this Guide project. However, many other contributors have given patches and
improvements to the text. Review the
[commit log in the Git repository](https://gitorious.org/copyleft-org/tutorial/commits/master)
[commit log in the Git repository](https://k.copyleft.org/guide/changelog)
for more details on who has contributed to the project.
## How Do I Get Involved?
The Guide is maintained in a copylefted distributed version control system called
[Git](http://git-scm.com/). Currently, the project utilizes the services of
a Git hosting website called [Gitorious](https://gitorious.org). (The
software which runs Gitorious is, itself, copylefted, too.)
[Git](http://git-scm.com/). Currently, the project collaboration site is an
instance of the [Kallithea code hosting software](https://kallithea-scm.org/)
hosted at [k.copyleft.org](https://k.copyleft.org/guide/). (Kallithea itself
us under a copyleft license, too, namely GPLv3.)
Those who are comfortable with Gitorious can submit
[merge requests on copyleft.org's gitorious site](https://gitorious.org/copyleft-org/tutorial/merge_requests).
Those who are comfortable with using Kallithea can submit
[pull requests via the Kallithea interface](https://k.copyleft.org/guide/pull-request).
See the section "Merge Request and Patch Workflow" below for more information
on the details of doing that.
However, lack of Git and/or LaTeX knowledge is *not a barrier* for
contribution to this project. Useful contributions will be accepted by the
following means as well:
@@ -108,13 +109,13 @@ procedures when doing so:
included because those parts aren't appropriate for the Guide).
This procedure creates a "commit point" that shows the specific text
brought from the other source — more-or-less as it stood in the
other work. This is useful for historical archiving purposes.
[Commit 678e841079aa708f98fe948ec8cef672d9a4c3cc](https://gitorious.org/copyleft-org/tutorial/commit/678e841079aa708f98fe948ec8cef672d9a4c3cc)
[Commit 678e841079aa708f98fe948ec8cef672d9a4c3cc](https://k.copyleft.org/guide/changeset/678e841079aa708f98fe948ec8cef672d9a4c3cc)
contains an example of this specific procedure.
2. In a second commit, by itself, add the following two things only:
* Update the copyright notices found in
[comprehensive-gpl-guide.tex](comprehensive-gpl-guide.tex). Ensure
@@ -138,72 +139,72 @@ procedures when doing so:
Ideally, all copyleft advocates would agree on all points, but they don't.
Therefore, the Guide should note the major differences in opinion in the
actual text, and include footnotes for any notable minority opinions.
Commit changes as necessary, in the smallest increments reasonably
possible.
[Commit 07a02b0b1c6d3ac2af9ed21b2a563abcf44d3d0f](https://gitorious.org/copyleft-org/tutorial/commit/07a02b0b1c6d3ac2af9ed21b2a563abcf44d3d0f)
[Commit 07a02b0b1c6d3ac2af9ed21b2a563abcf44d3d0f](https://k.copyleft.org/guide/changeset/07a02b0b1c6d3ac2af9ed21b2a563abcf44d3d0f)
is an example of the process for the last two steps.
5. Submit a merge request for your branch into 'next'. In this particular
situation, it's particularly helpful to make a formal merge request on
Gitorious rather than emailing a patch set.
## Merge Request and Patch Workflow
Currently, the main location for work on this project is
[on Gitorious](https://gitorious.org/copyleft-org/tutorial), and active new
[on k.copyleft.org](https://k.copyleft.org/guide), and active new
development on the project happens on the
['next' branch](https://gitorious.org/copyleft-org/tutorial/source/next:)
['next' branch](https://k.copyleft.org/guide/changelog?branch=next)
(which is
[auto-published on the copyleft.org/guide-next URL](https://copyleft.org/guide-next/)).
Here is a suggested workflow for submitting patches — first doing so
*with* the Gitorious infrastructure, second *avoiding* the Gitorious
infrastructure but still using Git, and third avoiding Git altogether.
Merge requests and/or patches against
['next' branch](https://gitorious.org/copyleft-org/tutorial/source/next:) are
['next' branch](https://k.copyleft.org/guide/changelog?branch=next) are
typically much preferred, and the workflow explanations below assume that.
However, merge requests and/or patches against
['master' branch](https://gitorious.org/copyleft-org/tutorial/source/master:)
['master' branch](https://k.copyleft.org/guide/changelog?branch=master)
are not necessarily rejected. In fact, if your change is a fix for typo,
spelling, grammar, formatting or anything urgent, submitting a patch against
'master' may make more sense.
To use the instructions below for proposals against the 'master' branch, just
replace 'next' everywhere below with 'master'.
### Contributing via Gitorious
### Contributing via copyleft.org's Kallithea instance
First-time contributors may want to do the following four items first:
0. [Create an account on Gitorious](https://gitorious.org/users/new)
0. [Create an account on k.copyleft.org](https://k.copyleft.org/_admin/register)
1. [Visit gitorious.org/copyleft-org/tutorial](https://gitorious.org/copyleft-org/tutorial)
and click "Clone".
1. [Visit k.copyleft.org/guide](https://k.copyleft.org/guide)
and choose "Fork" from the "Options" menu.
Instead of the default, you might call your clone
"MYNAME-copyleft-tutorial-suggestions".
"guide-USERNAME".
2. On the command line create a *local* clone of your Clone, by typing:
$ git clone git@gitorious.org:copyleft-org/MYNAME-copyleft-tutorial-suggestions.git copyleft-tutorial
$ cd copyleft-tutorial
$ git remote rename origin MYNAME-copyleft-tutorial-suggestions
$ git clone https://USERNAME@k.copyleft.org/guide-USERNAME copyleft-guide
$ cd copyleft-guide
$ git remote rename origin guide-USERNAME
(The last part isn't strictly necessary; you just might want to name the
upstream repository a more descriptive name, since below you'll add the
official repository as well).
3. Now, add to your clone a copy of the "real" copyleft.org tutorial
repository, and make a branch that tracks the official version:
$ git remote add copyleft-tutorial-official git@gitorious.org:copyleft-org/tutorial.git
$ git fetch copyleft-tutorial-official
$ git branch --track official-next copyleft-tutorial-official/next
$ git remote add guide-official https://bkuhn@k.copyleft.org/guide
$ git fetch guide-official
$ git branch --track official-next guide-official/next
That completes the first-time setup. Next is a workflow each proposed merge
request.
0. First, ensure the Git repository points at the right branch and all old
changes are committed.
@@ -219,14 +220,14 @@ request.
some other situation, which is beyond the scope of this document.
1. Now, get the most recent version of the 'next' branch:
$ git checkout master
$ git branch -D official-next
$ git branch --track official-next gude-official/next
$ git checkout official-next
$ git pull
(This step is more complicated than is typically found in a tutorial like
this. Experienced Git users will note the above is the easiest way to
handle the fact that the 'next' branch is occasionally rebased against
@@ -255,26 +256,25 @@ request.
$ git status
# On branch my-new-idea-for-tutorial
nothing to commit (working directory clean)
4. Next, upload and publish those ideas to your own clone on Gitorious.
$ git push MYNAME-copyleft-tutorial-suggestions my-new-idea-for-tutorial
$ git push guide-USERNAME my-new-idea-for-tutorial
That's the end of the command-line part.
5. Now, visit Gitorious' merge-request creation web interface at
https://gitorious.org/copyleft-org/MYNAME-copyleft-tutorial-suggestions/merge_requests/new
5. Now, visit the Kallithea pull request merge-request creation web interface at
https://k.copyleft.org/guide-USERNAME/pull-request
Initiate your merge request with by setting:
Summary: Briefly describe your proposal
Title: Briefly describe your proposal
Description: More completely describe your proposal
Target: tutorial
Target Branch: next
Source Branch: my-new-idea-for-tutorial
Original Repository: guide-USERNAME : my-new-idea-for-tutorial
Destination Repository: guide (parent) : next
6. While it's possible to discuss the details of the merge request via the
web interface, for larger changes, it may be worthwhile to start a thread
on
[the mailing list](http://lists.copyleft.org/cgi-bin/mailman/listinfo/discuss)
about the merge request. Include the URL of the merge request in the