Title: replace erroneous mentions of 'Gitorious' with 'Kallithea'
No description
Under review
1 reviewer
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
  • Bradley Kuhn (bkuhn)
1 comment (0 inline, 1 general)
Showing 1 commit
1 2016-11-05 11:13:46
bill-auger
eeb3b354b2d3 patch-contributing-md
replace erroneous mentions of 'Gitorious' with 'Kallithea'
Common ancestor: 85bbbf1ec649
1 file changed with 6 insertions and 5 deletions:
CONTRIBUTING.md | master patch-contributing-md
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!
1 comment (0 inline, 1 general)
bill auger (bill-auger)
1 year and 8 months ago on pull request "replace erroneous mentions of 'Gitorious' with 'Kallithea'"

Status change: Under review