diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 08dd8a65f3ab7c831670108f1c4ec988195d365d..a198162b0ac7d7f4944c98edb950dd67b295f345 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 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 @@ -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 + Description: More completely 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 remote set-url origin https://k.copyleft.org/guide + $ 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!