File diff 26def8538a10 → 0a5d6db00372
CONTRIBUTING.md
Show inline comments
...
 
@@ -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 fetch copyleft-tutorial-official
 
        $ git branch --track official-next copyleft-tutorial-official/next
 
        $ git fetch guide-official
 
        $ 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