From 0e49270eb14ec069908e19b36f90da59de1ee0ff 2014-12-23 02:16:33 From: Bradley M. Kuhn Date: 2014-12-23 02:16:33 Subject: [PATCH] Contributing text from third-party works. Integration of text from third-party works is complicated, since the text must be incorporated to flow properly with the rest of the Guide. Also, historical archiving commits are particularly useful in such situations. This tutorial explains how to contribute such additions for this project. --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63a29bce748464ee24fd710c544e8cf331eef23d..08dd8a65f3ab7c831670108f1c4ec988195d365d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,7 +67,86 @@ like to help there, such help is also welcome. ## Contributing Third-Party CC-BY-SA'd Works -FIXME +As can be seen in +[the LaTeX source file, third-party-citations.tex](third-party-citations.tex), +some material from third-party works has occasionally been merged into this +guide. We're always on the hunt for useful CC-BY-SA'd materials that would +work well with this guide. + +Do offer merge requests and/or patches that incorporate useful third-party +works, provided that is clearly licensed under CC-BY-SA. Follow these +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). + +1. If possible, follow this procedure for the first commit that begins the + work of integrating the third party text. + + Initially, just "paste in" any useful text from the other work into the + appropriate .tex file. Try to keep it as similar to the upstream sourced + text as possible. Surround the text with '% FIXME: ' as needed to remind + that editing is needed to integrate the text into document. Then, commit + this just as a stand-alone commit without any attempt to integrate the + text. + + While not strictly necessary, it's ideal to set the "Author" field and + "Author-Date" fields of this first commit to match the original author of + the work, rather than your own. You can do this with a command like this: + + $ 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 + + Write a commit message that specifically identifies the original author, + the original title of the published work. Include specific details + stating the reasons why you believe the work is licensed under CC-BY-SA. + If the original published work has a canonical hyperlink for the work, + include that as well in the commit message. + + Finally, include any comments or reasoning why the text is appropriate for + the Guide (and/or, why some text from the original material is not + 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) + 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 + that the LaTeX formatting is correct. + + * Add an entry in + [third-party-citations.tex](third-party-citations.tex) with a link to + the work. Mimic the formatting of existing '\item' entries on the + list already in that file. + +3. Next, through a series of small commits, carefully integrate the text into + the larger whole. Think carefully about how the new text will appear to + readers. Rework phrases as necessary to match the style of the existing + text of the Guide; pay particular attention to the style in the paragraphs + immediately surrounding your pastes to ensure the text reads a unified + whole. Commit changes as necessary, in the smallest increments reasonably + possible. + +4. Carefully vet the text for locations where the positions contradict or + otherwise aren't fully congruent with the existing material in the Guide. + 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) + 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