Title: replace erroneous mentions of 'Gitorious' with 'Kallithea'
No description
git pull https://k.copyleft.org/guide-bill-auger patch-contributing-md
2016-11-05 07:36:13
bill auger (bill-auger)
mr.j.spam.me@gmail.com
Git pull requests don't support updates yet.
Pull Request Reviewers
 1 1 # Contributions Welcome!  2 2 3 3 The maintainers of this Copyleft Guide project encourage contribution from  4 4 the community. Part of the impetus for this project was to create a  5 5 community around a "copyleft codebase" for information about copyleft. In  6 6 other words, this project is a tutorial project about Copyleft that is like a  7 7 Free Software project.  8 8 9 9 ## Who Is In Charge?  10 10 11 11 Currently, [Bradley M. Kuhn](http://ebb.org/bkuhn/) is the editor-in-chief of  12 12 this Guide project. However, many other contributors have given patches and  13 13 improvements to the text. Review the  14 14 [commit log in the Git repository](https://k.copyleft.org/guide/changelog)  15 15 for more details on who has contributed to the project.  16 16 17 17 ## How Do I Get Involved?  18 18 19 19 The Guide is maintained in a copylefted distributed version control system called  20 20 [Git](http://git-scm.com/). Currently, the project collaboration site is an  21 21 instance of the [Kallithea code hosting software](https://kallithea-scm.org/)  22 22 hosted at [k.copyleft.org](https://k.copyleft.org/guide/). (Kallithea itself  23 23 us under a copyleft license, too, namely GPLv3.)  24 24 25 25 Those who are comfortable with using Kallithea can submit  26 26 [pull requests via the Kallithea interface](https://k.copyleft.org/guide/pull-request).  27 27 See the section "Merge Request and Patch Workflow" below for more information  28 28 on the details of doing that.  29 29 30 30 However, lack of Git and/or LaTeX knowledge is *not a barrier* for  31 31 contribution to this project. Useful contributions will be accepted by the  32 32 following means as well:  33 33 34 34  * Patches posted to  35 35  [the mailing list](http://lists.copyleft.org/cgi-bin/mailman/listinfo/discuss).  36 36 37 37  * New sections of text or simply ideas and input emailed to  38 38  [the mailing list](http://lists.copyleft.org/cgi-bin/mailman/listinfo/discuss).  39 39 40 40  * Ideas and suggestions mentioned on the  41 41  [irc channel #copyleft on freenode](irc://irc.freenode.net/#copyleft).  42 42 43 43 Please, do not worry if your patches or new sections of text are not properly  44 44 formatted as patches and/or are not formatted in LaTeX properly. Indeed,  45 45 feel free to offer patches that break LaTeX formatting, or to just write up  46 46 your suggestion in an email. If the content is appropriate for the Guide,  47 47 the editor-in-chief or someone else will format your contribution properly  48 48 for LaTeX.  49 49 50 50 Note: by submitting contributions via any of these means, you agree to the  51 51 "Author's Certificate of Origin" (see below).  52 52 53 53 ## How Do I Figure Out What To Contribute?  54 54 55 55 If you're looking for something to fix, just grep the *.tex files for "FIXME"  56 56 and you'll find plenty. Many of them are simple and easy to do. Some of  57 57 them are writing, and some of them are simply formatting-related.  58 58 59 59 If you want a larger, more involved writing project, take a look at the  60 60 [TODO list in this repository](TODO.md). That list has bigger items that  61 61 other contributors have identified as necessary. (BTW, the project  62 62 contributors are considering various possible copylefted bug-tracking  63 63 solutions, but admittedly haven't picked a bug-tracker yet.)  64 64 65 65 There is also a [TODO list on the website](https://copyleft.org/todo/), which  66 66 are mostly related to formatting, layout and infrastructure, but if you'd  67 67 like to help there, such help is also welcome.  68 68 69 69 ## Contributing Third-Party CC-BY-SA'd Works  70 70 71 71 As can be seen in  72 72 [the LaTeX source file, third-party-citations.tex](third-party-citations.tex),  73 73 some material from third-party works has occasionally been merged into this  74 74 guide. We're always on the hunt for useful CC-BY-SA'd materials that would  75 75 work well with this guide.  76 76 77 77 Do offer merge requests and/or patches that incorporate useful third-party  78 78 works, provided that is clearly licensed under CC-BY-SA. Follow these  79 79 procedures when doing so:  80 80 81 81 0. Target all changes for the 'next' branch (see below). Likely, use of a  82 82  secondary branch will be useful for the following steps (perhaps use the  83  procedure below entitled "Contributing via Gitorious" to do so).  83  procedure below entitled "Contributing via copyleft.org's Kallithea  84  instance" to do so).  84 85 85 86 1. If possible, follow this procedure for the first commit that begins the  86 87  work of integrating the third party text.  87 88 88 89  Initially, just "paste in" any useful text from the other work into the  89 90  appropriate .tex file. Try to keep it as similar to the upstream sourced  90 91  text as possible. Surround the text with '% FIXME: ' as needed to remind  91 92  that editing is needed to integrate the text into document. Then, commit  92 93  this just as a stand-alone commit without any attempt to integrate the  93 94  text.  94 95 95 96  While not strictly necessary, it's ideal to set the "Author" field and  96 97  "Author-Date" fields of this first commit to match the original author of  97 98  the work, rather than your own. You can do this with a command like this:  98 99 99 100  $date="2014-05-31 13:15:01 -0400"; env GIT_AUTHOR_DATE="$date" GIT_AUTHOR_NAME="Original Author Name" GIT_AUTHOR_EMAIL="originalauthor@example.org" git commit -a  100 101 101 102  Write a commit message that specifically identifies the original author,  102 103  the original title of the published work. Include specific details  103 104  stating the reasons why you believe the work is licensed under CC-BY-SA.  104 105  If the original published work has a canonical hyperlink for the work,  105 106  include that as well in the commit message.  106 107 107 108  Finally, include any comments or reasoning why the text is appropriate for  108 109  the Guide (and/or, why some text from the original material is not  109 110  included because those parts aren't appropriate for the Guide).  110 111 111 112  This procedure creates a "commit point" that shows the specific text  112 113  brought from the other source — more-or-less as it stood in the  113 114  other work. This is useful for historical archiving purposes.  114 115 115 116  [Commit 678e841079aa708f98fe948ec8cef672d9a4c3cc](https://k.copyleft.org/guide/changeset/678e841079aa708f98fe948ec8cef672d9a4c3cc)  116 117  contains an example of this specific procedure.  117 118 118 119 2. In a second commit, by itself, add the following two things only:  119 120 120 121  * Update the copyright notices found in  121 122  [comprehensive-gpl-guide.tex](comprehensive-gpl-guide.tex). Ensure  122 123  that the LaTeX formatting is correct.  123 124 124 125  * Add an entry in  125 126  [third-party-citations.tex](third-party-citations.tex) with a link to  126 127  the work. Mimic the formatting of existing '\item' entries on the  127 128  list already in that file.  128 129 129 130 3. Next, through a series of small commits, carefully integrate the text into  130 131  the larger whole. Think carefully about how the new text will appear to  131 132  readers. Rework phrases as necessary to match the style of the existing  132 133  text of the Guide; pay particular attention to the style in the paragraphs  133 134  immediately surrounding your pastes to ensure the text reads a unified  134 135  whole. Commit changes as necessary, in the smallest increments reasonably  135 136  possible.  136 137 137 138 4. Carefully vet the text for locations where the positions contradict or  138 139  otherwise aren't fully congruent with the existing material in the Guide.  139 140  Ideally, all copyleft advocates would agree on all points, but they don't.  140 141  Therefore, the Guide should note the major differences in opinion in the  141 142  actual text, and include footnotes for any notable minority opinions.  142 143  Commit changes as necessary, in the smallest increments reasonably  143 144  possible.  144 145 145 146  [Commit 07a02b0b1c6d3ac2af9ed21b2a563abcf44d3d0f](https://k.copyleft.org/guide/changeset/07a02b0b1c6d3ac2af9ed21b2a563abcf44d3d0f)  146 147  is an example of the process for the last two steps.  147 148 148 149 5. Submit a merge request for your branch into 'next'. In this particular  149 150  situation, it's particularly helpful to make a formal merge request on  150  Gitorious rather than emailing a patch set.  151  Kallithea rather than emailing a patch set.  151 152 152 153 ## Merge Request and Patch Workflow  153 154 154 155 Currently, the main location for work on this project is  155 156 [on k.copyleft.org](https://k.copyleft.org/guide), and active new  156 157 development on the project happens on the  157 158 ['next' branch](https://k.copyleft.org/guide/changelog?branch=next)  158 159 (which is  159 160 [auto-published on the copyleft.org/guide-next URL](https://copyleft.org/guide-next/)).  160 161 Here is a suggested workflow for submitting patches — first doing so  161 *with* the Gitorious infrastructure, second *avoiding* the Gitorious  162 *with* the Kallithea infrastructure, second *avoiding* the Kallithea  162 163 infrastructure but still using Git, and third avoiding Git altogether.  163 164 164 165 Merge requests and/or patches against  165 166 ['next' branch](https://k.copyleft.org/guide/changelog?branch=next) are  166 167 typically much preferred, and the workflow explanations below assume that.  167 168 However, merge requests and/or patches against  168 169 ['master' branch](https://k.copyleft.org/guide/changelog?branch=master)  169 170 are not necessarily rejected. In fact, if your change is a fix for typo,  170 171 spelling, grammar, formatting or anything urgent, submitting a patch against  171 172 'master' may make more sense.  172 173 173 174 To use the instructions below for proposals against the 'master' branch, just  174 175 replace 'next' everywhere below with 'master'.  175 176 176 177 177 178 ### Contributing via copyleft.org's Kallithea instance  178 179 179 180 First-time contributors may want to do the following four items first:  180 181 181 182 0. [Create an account on k.copyleft.org](https://k.copyleft.org/_admin/register)  182 183 183 184 1. [Visit k.copyleft.org/guide](https://k.copyleft.org/guide)  184 185  and choose "Fork" from the "Options" menu.  185 186 186  Instead of the default, you might call your clone  187  Instead of the default, you might call your fork  187 188  "guide-USERNAME".  188 189 189 190 2. On the command line create a *local* clone of your Clone, by typing:  190 191 191 192  $git clone https://USERNAME@k.copyleft.org/guide-USERNAME copyleft-guide  192 193 $ cd copyleft-guide  193 194  $git remote rename origin guide-USERNAME  194 195 195 196  (The last part isn't strictly necessary; you just might want to name the  196 197  upstream repository a more descriptive name, since below you'll add the  197 198  official repository as well).  198 199 199 200 3. Now, add to your clone a copy of the "real" copyleft.org tutorial  200 201  repository, and make a branch that tracks the official version:  201 202 202 203 $ git remote add guide-official https://bkuhn@k.copyleft.org/guide  203 204  $git fetch guide-official  204 205 $ git branch --track official-next guide-official/next  205 206 206 207 That completes the first-time setup. Next is a workflow each proposed merge  207 208 request.  208 209 209 210 0. First, ensure the Git repository points at the right branch and all old  210 211  changes are committed.  211 212 212 213  $git status  213 214 214 215  The output of the last command should look like this:  215 216 216 217  # On branch SOME_BRANCH  217 218  nothing to commit (working directory clean)  218 219 219 220  If you don't get that output, you probably have uncommitted changes from  220 221  some other situation, which is beyond the scope of this document.  221 222 222 223 1. Now, get the most recent version of the 'next' branch:  223 224 224 225 $ git checkout master  225 226  $git branch -D official-next  226 227 $ git fetch guide-official  227 228  $git branch --track official-next gude-official/next  228 229 $ git checkout official-next  229 230  $git pull  230 231 231 232  (This step is more complicated than is typically found in a tutorial like  232 233  this. Experienced Git users will note the above is the easiest way to  233 234  handle the fact that the 'next' branch is occasionally rebased against  234 235  master. If 'next' branch has not been rebased since the last time the  235 236  operation was performed, the last two commands suffice for this step.)  236 237 237 238 1. Next, create a new branch to hold your changes:  238 239 239 240 $ git checkout -b my-new-idea-for-tutorial official-next  240 241 241 242  Use a name that briefly describes your planned proposal for  242 243  "my-new-idea-for-tutorial".  243 244 244 245 2. Make your edits. If you're editing the tutorial, you likely want to focus  245 246  on the files ending in '.tex'. Commit frequently while you're editing  246 247  with:  247 248 248 249  $git commit -a  249 250 250 251  Write useful and clear commit messages that explain the purpose of the  251 252  changes.  252 253 253 254 3. When you are done all the changes related to 'my-new-idea-for-tutorial',  254 255  verify they've all been committed this way:  255 256 256 257 $ git status  257 258  # On branch my-new-idea-for-tutorial  258 259  nothing to commit (working directory clean)  259 260 260 4. Next, upload and publish those ideas to your own clone on Gitorious.  261 4. Next, upload and publish those ideas to your own fork on Kallithea.  261 262 262 263  $git push guide-USERNAME my-new-idea-for-tutorial  263 264 264 265  That's the end of the command-line part.  265 266 266 267 5. Now, visit the Kallithea pull request merge-request creation web interface at  267 268  https://k.copyleft.org/guide-USERNAME/pull-request  268 269 269 270  Initiate your merge request with by setting:  270 271 271 272  Title: Briefly describe your proposal  272 273  Description: More completely describe your proposal  273 274  Original Repository: guide-USERNAME : my-new-idea-for-tutorial  274 275  Destination Repository: guide (parent) : next  275 276 276 277 6. While it's possible to discuss the details of the merge request via the  277 278  web interface, for larger changes, it may be worthwhile to start a thread  278 279  on  279 280  [the mailing list](http://lists.copyleft.org/cgi-bin/mailman/listinfo/discuss)  280 281  about the merge request. Include the URL of the merge request in the  281 282  post.  282 283 283 284 ## Gitorious Apocalypse Recovery  284 285 285 286 If you used to contribute via Gitorious, *don't panic*! We were careful to  286 287 transition the project to Kallithea without requiring recloning the  287 288 repository. If you initially did a clone of the main repository (i.e., not  288 289 your own clone) all you need to do one of these operations  289 290 290 291 For Git 1.8.0 or later:  291 292 292 293 $ git remote set-url origin https://k.copyleft.org/guide  293 294  $git --set-upstream master origin/master  294 295 $ git --set-upstream-to next origin/next  295 296 296 297 For any older version of Git:  297 298 298 299  $git remote set-url origin https://k.copyleft.org/guide  299 300 $ git config branch.master.remote https://k.copyleft.org/guide  300 301  \$ git config branch.next.remote https://k.copyleft.org/guide  301 302 302 303 (If you renamed the gitorious remote to a different name, replace "origin"  303 304 with the name you used. If you previously followed the workflow instructions  304 305 above, yours is probably called "guide-official", or "tutorial-official",  305 306 rather than "origin").  306 307 307 308 It's really that simple!  308 309 309 310 If you had a clone on gitorious, you have a bit more work to do, but feel  310 311 free to create a clone on k.copyleft.org and push any branches you care about  311 312 there!