@@ -9,20 +9,24 @@ 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)
this Guide project. Bradley shares commit access with Ben Cotton, Donald
Roberston, and Engel Nyst.
Also, many other contributors have given patches and improvements to the
text. Review the
[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.
@@ -79,7 +83,8 @@ procedures when doing so:
0. Target all changes for the 'next' branch (see below). Likely, use of a
secondary branch will be useful for the following steps (perhaps use the
procedure below entitled "Contributing via Gitorious" to do so).
procedure below entitled "Contributing via copyleft.org's Kallithea
instance" to do so).
1. If possible, follow this procedure for the first commit that begins the
work of integrating the third party text.
@@ -111,7 +116,7 @@ procedures when doing so:
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:
@@ -141,7 +146,7 @@ procedures when doing so:
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
@@ -151,9 +156,9 @@ procedures when doing so:
## 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
@@ -161,35 +166,37 @@ Here is a suggested workflow for submitting patches — first doing so
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'.
replace 'next' everywhere below with 'master'. However, please read below
the section entitled "Why Changes Should Target 'next' Branch" below before
pushing anything to the master branch.
### 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
@@ -198,9 +205,9 @@ First-time contributors may want to do the following four items first:
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.
@@ -222,8 +229,8 @@ request.
$ git checkout master
$ git branch -D official-next
$ git branch --track official-next gude-official/next
$ git checkout official-next
$ git pull
@@ -258,20 +265,19 @@ request.
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
Description: More completely describe your proposal
Target: tutorial
Target Branch: next
Source Branch: my-new-idea-for-tutorial
Title: Briefly describe your proposal
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
@@ -279,3 +285,58 @@ request.
[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
post.
## Why Changes Should Target 'next' Branch
The instructions above encourage you to submit your changes to the 'next'
branch, which is found
[on k.copyleft.org](https://k.copyleft.org/guide/files/next), and is
auto-deployed to
[copyleft.org/guide-next/](https://copyleft.org/guide-next/).
The "official" Copyleft Guide is published on
[copyleft.org/guide/](https://copyleft.org/guide/) automatically from the
'master' branch of the repository.
Since many use this Guide as a reference, non-trivial changes are merged into
the "official" Copyleft Guide carefully and only after
discussion on
[the mailing list](http://lists.copyleft.org/cgi-bin/mailman/listinfo/discuss).
There is one key rule with regard to merging changes from 'next' to 'master':
> Treat 'master' branch as if by committing there, you have single-handledly
> defined for the world what copyleft is.
If you have commit access to the public master branch, please carefully head
this.
## Gitorious Apocalypse Recovery
If you used to contribute via Gitorious, *don't panic*! We were careful to
transition the project to Kallithea without requiring recloning the
repository. If you initially did a clone of the main repository (i.e., not
your own clone) all you need to do one of these operations
For Git 1.8.0 or later:
$ git remote set-url origin https://k.copyleft.org/guide
$ git --set-upstream master origin/master
$ git --set-upstream-to next origin/next
For any older version of Git:
$ git config branch.master.remote https://k.copyleft.org/guide
$ git config branch.next.remote https://k.copyleft.org/guide
(If you renamed the gitorious remote to a different name, replace "origin"
with the name you used. If you previously followed the workflow instructions
above, yours is probably called "guide-official", or "tutorial-official",
rather than "origin").
It's really that simple!
If you had a clone on gitorious, you have a bit more work to do, but feel
free to create a clone on k.copyleft.org and push any branches you care about
there!