CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" /> <title>GitHub guidelines for working with i18n documents</title> <meta name="description" content="Helps members of the W3C Internationalization Activity work with GitHub." /> <script> var f = { } // AUTHORS should fill in these assignments: f.directory = 'guidelines'+'/'; // the path to this file, not including /International or the file name f.filename = 'github'; // the file name WITHOUT extensions f.authors = 'Richard Ishida, W3C'; // author(s) and affiliations f.previousauthors = ''; // as above f.modifiers = ''; // people making substantive changes, and their affiliation f.searchString = 'level2-github'; // blog search string - usually the filename without extensions f.firstPubDate = '2015-12-16'; // date of the first publication of the document (after review) f.lastSubstUpdate = { date:'2016-10-11', time:'07:50'} // date and time of latest substantive changes to this document f.status = 'notreviewed'; // should be one of draft, review, published, notreviewed or obsolete f.path = '../' // what you need to prepend to a URL to get to the /International directory // AUTHORS AND TRANSLATORS should fill in these assignments: f.thisVersion = { date:'2021-04-27', time:'12:18'} // date and time of latest edits to this document/translation f.contributors = ''; // people providing useful contributions or feedback during review or at other times // also make sure that the lang attribute on the html tag is correct! // TRANSLATORS should fill in these assignments: f.translators = 'xxxNAME, ORG'; // translator(s) and their affiliation - a elements allowed, but use double quotes for attributes f.breadcrumb = ''; f.additionalLinks = '' </script> <script src="file-data/translations.js"> </script> <script src="../../i18n-drafts/javascript/doc-structure/article-dt.js"> </script> <script src="../../i18n-drafts/javascript/boilerplate-text/boilerplate-en.js"></script>  <script src="../../i18n-drafts/javascript/doc-structure/sitepage-2022.js"> </script> <script src="../../i18n-drafts/javascript/articletoc-2022.js"></script> <link rel="stylesheet" href="../../i18n-drafts/style/sitepage-2022.css" /> <link rel="copyright" href="#copyright"/> </head> <body> <header> <nav id="mainNavigation"></nav><script>document.getElementById('mainNavigation').innerHTML = mainNavigation</script> </header> <h1>GitHub guidelines for working with i18n documents</h1> <section id="sidebarExtras"> </section> <div id="mainLayout"> <section> <p>The W3C Internationalization Activity has task forces which use GitHub for document development. This page provides guidelines to help people contribute content if they are unfamiliar with GitHub. Some of this information is a shameless copy of text from <a href="http://web-platform-tests.org/writing-tests/github-intro.html">the Test the Web Forward documentation</a>.</p> <p>For the examples we will use the GitHub username <span class="highlightedterm">myUserName</span> and we'll use a repository (repo) name, <span class="highlightedterm">repoName</span>. You should substitute your own username wherever you see <span class="qterm">myUserName</span>, and the name of the repo you want to work with for <span class="qterm">repoName</span>.</p> <p>If you have comments or suggestions about how to improve this page, feel free to <a href="https://github.com/w3c/i18n-activity/issues">raise a GitHub issue</a>.</p> <p>See also the <a href="editing">editorial guidelines</a>.</p> </section> <section id="setup"> <h2>Setting up GitHub</h2> <p>If you haven't used GitHub before, follow the instructions in this section. Otherwise, skip to the next section.</p> <ol> <li> <p>Create a GitHub account if you do not already have one, on <a href="https://github.com/">github.com</a></p> </li> <li> <p>Download and install the latest version of Git: <a href="https://git-scm.com/downloads">https://git-scm.com/downloads</a>. Please refer to the instructions there for different platforms.</p> </li> <li> <p>Configure your settings so your commits are properly labeled:</p> <ol> <li><p>On Mac or Linux or Solaris, open the Terminal.</p> <p>On Windows, open Git Bash (From the Start Menu > Git > Git Bash).</p></li> <li><p>At the prompt, type:</p> <pre>$ git config --global user.name "Your Name" </pre> <p>This will be the name that is displayed with your test submissions</p></li> <li><p>Next, type:</p> <pre>$ git config --global user.email "your_email@address.com" </pre> <p>This should be the email address you used to create the account in Step 1.</p></li> <li><p>Then type:</p> <pre>$ git config --global push.default upstream </pre> <p>This ensures that git push will never unintentionally create or update a remote branch.</p></li> </ol> </li> <li> <p>(Optional) If you don't want to enter your username and password every time you talk to the remote server, you'll need to set up password caching. See <a href="https://help.github.com/articles/caching-your-github-password-in-git">Caching your GitHub password in Git</a>.</p> </li> </ol> </section> <section id="basics"> <h2>Basic overview of how the process works</h2> <p>The repository that you contribute to will depend on the document that your task force is working on. For example, <a href="https://github.com/w3c/alreq">https://github.com/w3c/alreq</a>. The following diagram illustrates the basics.</p> <p><img src="images/github-entities.png" style="width: 100%;" alt="Diagram showing parts of the GitHub setup."/></p> <p>We'll spend a moment in this section familiarising you with the basic setup. The following sections will indicate the detailed steps you need to take.</p> <p>In a typical scenario, you will be working with an <span class="highlightedterm">upstream</span> repository (repo) that has a URL beginning with <span class="url" translate="no">https://github.com/<strong>w3c</strong>/</span>. This is the <span class="highlightedterm">W3C repo</span> – it is managed by the people who have editor access for your project, unless you are one of those people you don't have access to this, you can only propose changes to it. You will make a <span class="highlightedterm">fork</span> of that repo on GitHub, which has a URL beginning with <span class="url" translate="no">https://github.com/<strong>myUserName</strong></span>. A fork is basically just a copy of the W3C repository in which you can change things at will. It sits on the GitHub server and from time to time will be referred to in this document as the <span class="highlightedterm">origin</span>.</p> <p>Then you will typically <span class="highlightedterm">clone</span> your fork to a directory on your local computer, to make it easier to edit content with authoring tools and the like, however it is also possible just edit on the GitHub site. </p> <p>If you have cloned your fork to your desktop, you should update it regularly so that it matches the W3C repo. You do this by <span class="highlightedterm">fetching</span> the changes from the W3C repo to your local copy and <span class="highlightedterm">merging</span> them with what's on your hard disk. You'll then need to <span class="highlightedterm">push</span> those changes on to your fork on GitHub, so that that is in synch too.</p> <p>As you edit content files on your computer, you'll need to get them into your fork on GitHub. To do this you need to select the files and <span class="highlightedterm">add</span> them (which basically just identifies them as ready for the next stage). Then you <span class="highlightedterm">commit</span> them, and finally you <span class="highlightedterm">push</span> them (upload them) to your fork.</p> <p>Usually, prior to doing the add, commit, push routine, you would create a <span class="highlightedterm">branch</span>. This is rather like a walled garden within which you'll be making and managing changes. You can have any number of branches.</p> <p>Once you have made changes and you want to send those for incorporation into the W3C repo, and once you have pushed those changes to your fork on the GitHub site, you raise a <span class="highlightedterm">pull request</span> for the branch you were working in. The pull request informs the guardians of the W3C repo that you want to contribute some changes. Those guardians may simply merge your changes into the W3C repo, but typically they will look at your suggestions and allow some time for others to review them. You may need to change some things in the light of feedback before your content is merged with the W3C repo. Sometimes, the editors may take your code and add parts of it or add something along similar lines, rather than just merging the documents.</p> </section> <section id="forking"> <h2>How to make your fork</h2> <p>Once you have Git set up, you will need to fork the test repository. This will enable you to submit your proposed changes using a pull request (more on this below).</p> <ol> <li> <p>In the browser, go the the GitHub page for the W3C repository, ie. <span class="url">https://github.com/w3c/<em>repoName</em>/</span>. </p> </li> <li> <p>Click the <img src="images/forkbtn.png" alt="fork"> button in the upper right.</p> </li> <li> <p>The fork will take several seconds, then you will be redirected to your GitHub page for this forked repository, ie. <span class="url">https://github.com/<em>myUserName</em>/<em>repoName</em>/</span>.</p> </li> </ol> </section> <section id="cloning"> <h2>Cloning your forked repo to your desktop</h2> <p>If your fork was successful, the next step is to clone (download) a copy of your forked repo.</p> <p>At the command prompt, use <kbd>cd</kbd> to get to a directory where you want to keep your fork. We're about to create a subdirectory within the directory you just moved to: the subdirectory will be called <samp>repoName</samp>, and will contain all the files for that fork.</p> <p>Type the following:</p> <pre>$ git clone https://github.com/<var>myUserName</var>/<var>repoName</var>.git</pre> <p>where <span class="qterm">myUserName</span> is your GitHub username, and <span class="qterm">repoName</span> is the name of the repository. This will download the forked repository into the subdirectory we just mentioned.</p> <p>You should now have a full copy of the forked repository on your local machine. Feel free to browse the directories on your hard drive. You can also browse them on <a href="https://github.com/w3c">github.com</a> and see the full history of contributions there.</p> </section> <section id="housekeeping"> <h2>Additional housekeeping</h2> <p>You should do a little housekeeping before going further.</p> <ol> <li> <p>On the command line, navigate to the directory where your forked copy of the repository is located.</p> <pre>$ cd <pathname>/<em>repoName</em> </pre></li> <li> <p>Make sure that you are on the <span class="highlightedterm">gh-pages branch</span>. This will be the case if you just forked. Type</p> <pre>$ git status</pre> <p>You should see several lines, one of which will say</p> <pre>On branch gh-pages</pre> <p>If you are on another branch, switch to gh-pages by typing</p> <pre>$ git checkout gh-pages </pre> </li> <li> <p>Next, check that git knows about the upstream repository you forked (ie. the W3C repo). This assigns the W3C repository to "upstream":</p> <pre>$ git remote -v </pre> <p>It should say </p> <pre>origin https://github.com/<em>myUserName</em>/<em>repoName</em>.git (fetch) origin https://github.com/<em>myUserName</em>/<em>repoName</em>.git (push) upstream https://github.com/w3c/<em>repoName</em>.git (fetch) upstream https://github.com/w3c/<em>repoName</em>.git (push)</pre> <p>If it doesn't, set upstream as follows:</p> <pre>$ git remote add upstream https://github.com/w3c/<em>repoName</em>.git </pre> </li> </ol> </section> <section id="synchronising"> <h2>Synchronising your local files and your fork with the W3C repo</h2> <p>You should regularly bring your local copy of the files up-to-date with the latest commits in the W3C repository.</p> <ol> <li> <p>On the command line, navigate to the directory where your forked copy of the repository is located.</p> <pre>$ cd <pathname>/<em>repoName</em> </pre></li> <li> <p>Make sure that you are on the <span class="highlightedterm">gh-pages branch</span>. This will be the case if you just forked, otherwise switch to <code class="kw" translate="no">gh-pages</code>.</p> <pre>$ git checkout gh-pages</pre> </li> <li> <p>To pull in changes in the W3C repository that are not present in your local repository first <span class="highlightedterm">fetch</span> them:</p> <pre>$ git fetch upstream</pre> <p>Then merge them into the directories on your local system:</p> <pre>$ git merge upstream/gh-pages </pre> </li> <li> <p>Finally you will want to make sure that these changes get into your forked repo on GitHub too. To do this, push the changes to your fork:</p> <pre>$ git push</pre> </li> </ol> <p>For additional information, please see the <a href="https://help.github.com/articles/fork-a-repo">GitHub docs</a>.</p> </section> <section id="changing"> <h2>Making changes and proposing them</h2> <p>Now we describe steps to create content and how to request that the changes be merged into the content on the W3C repo.</p> <p><span class="highlightedterm">Before you start on these steps</span>, ensure that you have fetched the latest files from the W3C repo by following the steps in the previous section! </p> <p><span class="highlightedterm">Also, ensure that</span> you start from the <code class="kw" translate="no">gh-pages</code> branch, otherwise you'll end up with a horrible nested mess and you'll be very embarrassed because someone will have to spend a while digging you out. You have been warned!</p> <section id="newbranch"> <h3>Create a new branch</h3> <p>At the command line, check you are on the <code class="kw" translate="no">gh-pages</code> branch by typing</p> <pre>$ git status</pre> <p>If not, then type</p> <pre>$ git checkout gh-pages</pre> <p>Then create a <span class="highlightedterm">new branch</span>:</p> <pre>$ git checkout -b <em>myBranchName</em></pre> <p>This will create a branch named <code class="kw" translate="no">myBranchName</code><code></code> and immediately switch this to be your active working branch.</p> <p>The branch name should describe specifically what you are working on. For example:</p> <pre>$ git checkout -b arabic-joining-forms </pre> </section> <section id="makeChanges"> <h3>Make the changes to your content</h3> <p>Edit the files you want to change or create.</p> </section> <section id="prepare"> <h3>Prepare your files for submission</h3> <p>Before you submit your changes for review and contribution to the W3C repo, you'll need to first commit them locally, where you now have your own personal version control system with git. In fact, as you are making your changes, you may want to save versions of your work as you go before you submit them to be reviewed and merged.</p> <ol> <li> <p>When you're ready to save a version of your work, go to the command prompt and cd to the directory where your files are.</p> </li> <li> <p>First, ask git what new or modified files you have:</p> <pre>$ git status</pre> <p>This will show you files that have been added or modified.</p> </li> <li> <p>For all new or modified files, you need to tell git to <span class="highlightedterm">add</span> them to the list of things you'd like to commit:</p> <pre>$ git add [file1] [file2] ... [fileN]</pre> <p>Or:</p> <pre>$ git add [directory_of_files]</pre> </li> <li> <p>Run <code>git status</code> again to see what you have on the 'Changes to be committed' list. These files are now <span class="qterm">staged</span>.</p> <p>(Alternatively, you can run <code>git diff --staged</code>, which will show you the diff of things to be committed.)</p> </li> <li> <p>Once you've added everything, you can <span class="highlightedterm">commit</span> and add a message to this set of changes:</p> <pre>$ git commit -m "New section on Arabic joining forms"</pre> <p>Make the message as short but as informative as possible. Others will need to get a clear idea of what these changes are about by reading this text.</p> </li> <li> <p>Repeat these steps as many times as you'd like before you submit your changes for inclusion in the W3C repo.</p> </li> </ol> </section> <section id="request"> <h3>Request that your changes be incorporated into the W3C repo</h3> <ol> <li> <p>The first thing you do before submitting changes to the W3C repo is to push them back up to your fork on the server:</p> <pre>$ git push origin <em>myBranchName</em></pre> <p> Here, <code>origin</code> refers to your fork of the repo on the GitHub server. You just use the word origin, git should know where that is. <code class="kw" translate="no">myBranchName</code> should be the name of your branch that created earlier.</p> </li> <li> <p>Now you can send a message that you have changes or additions you'd like to be reviewed and merged into the W3C repository. You do this by using a pull request. In a browser, open the GitHub page for your forked repository, ie. <span class="url">https://github.com/<em>myUserName</em>/<em>repoName</em>/</span>.</p> </li> <li> <p>Now create a <span class="highlightedterm">pull request</span>. There are several ways to create a PR in the GitHub UI. Below is one method and others can be found on <a href="https://help.github.com/articles/creating-a-pull-request">github.com</a></p> <p>a. Click on the <img src="images/new-pull-request.png" alt="new pull request"> button. You should see something like this:</p> <p><img src="images/pr-panel-large.png" style="width: 150%; max-width: 809px;" alt=""/></p> <p>b. Pay careful attention to the line of buttons at the top of the picture above. Here's an example:</p> <p><img src="images/pr-panel-buttons.png" style="width: 150%; max-width: 809px;" alt=""/></p> <p style="width: 150%; max-width: 809px;">Moving from left to right, the first button should say <span class="ghButton">base fork: w3c/<code class="kw" translate="no">repoName</code></span>, the second <span class="ghButton">base: gh-pages</span>, the third, <span class="ghButton">head fork: <code class="kw" translate="no">myUserName/repoName</code></span>, and the one on the right should read <span class="ghButton">compare: <code class="kw" translate="no">myBranchName</code></span>.</p> <div class="insideinfonote"> <p class="info">Substitute the appropriate names for <code class="kw" translate="no">repoName</code>, <code class="kw" translate="no">myUserName</code> and <code class="kw" translate="no">myBranchName</code>.</p> </div> <p>If you see <em>'There isn't anything to compare'</em>, make sure your fork and your branch are selected on the right side.</p> <p>f. If you'd like to add more detailed comments or a title other than one that is suggested, edit the fields below the buttons.</p> <p>g. Click <img src="images/sendpullrequest.png" alt="the send pull request button"></p> </li> <li> <p>Wait for feedback on your pull request.</p> </li> </ol> </section> <section id="modify"> <h3>Modify your submission</h3> <p>Once you submit your pull request, a reviewer will check your proposed changes for correctness and style. It is likely that this process will lead to some comments asking for modifications to your code. When you are ready to make the changes, follow these steps:</p> <ol> <li> <p>If you are no longer in the branch you were previously working on (in examples above this was <code>myBranchName</code>), check it out again, eg.</p> <pre>$ git checkout myBranchName</pre> </li> <li> <p>Make the changes needed to address the comments, and commit them just like before.</p> </li> <li> <p>Push the changes to the branch on your forked repo:</p> <pre>$ git push origin myBranchName</pre> </li> <li> <p>The pull request will automatically be updated with the new commit.</p> </li> </ol> <p>Sometimes it takes multiple iterations through a review before the changes are finally accepted. Don't worry about this, it's totally normal. The goal of review is to work together to create the best possible content for your task force.</p> </section> <section id="cleanup"> <h3>Cleaning up</h3> <p>Once your pull request has been accepted, you will be notified in the GitHub UI and you may get an email. At this point, your changes have been merged into the W3C repo. You do not need to take any further action on the files you submittted, but you should delete your branch. This can easily be done in the GitHub UI by navigating to the pull requests and clicking the 'Delete Branch' button.</p> <p><img src="images/praccepteddelete.png" alt="pull request accepted delete branch"></p> <p>Alternatively, you can delete the branch on the command line.</p> <pre>$ git push origin --delete <em>myBranchName</em></pre> <p>Then fetch the latest files from the W3C repo and push them to your fork, as described earlier, so that you are up to date with everything.</p> </section> </section> <section id="hints"> <h2>GitHub hints & tips</h2> <section id="liveview"> <h3>See an HTML version of a page from a commit diff page</h3> <p>You're looking at the diff for a commit (eg. <a href="https://github.com/w3c/alreq/commit/404f75daa4f6bb83750db85eee92b73371759842">this one</a>), and i want to see what the HTML page would look like. How do you do that?</p> <ol> <li> <p>At the diff page, click on the View button</p> </li> <li> <p>Pick up the commit number from the address bar</p> <p class="hint">eg. 8be942ceb6ba109309f8371b7845011ed1ee63c1</p> </li> <li> <p>Open a browser window and go to the following URL, filling in the placeholders as appropriate:</p> <p class="hint">https://htmlpreview.github.io/?https://github.com/<em>w3c</em>/<em>repoName</em>/blob/<em>commitNumber</em>/<em>fileName</em></p></li> </ol> <p>So <a href="https://htmlpreview.github.io/?https://github.com/w3c/alreq/blob/404f75daa4f6bb83750db85eee92b73371759842/index.html">here's the HTML version</a> of the page with the commit in the example at the start of this section.</p> <p>Alternatively, you can point to files you have included in a pull request in your own fork (origin) using rawgit. Just construct the following URL: <span class="hint">https://rawgit.com/w3c/<em>repoName</em>/<em>branchName</em>/<em>path_and_filename</em>.html</span></p> </section> </section> <section id="echidna"> <h2>Publishing with Echidna</h2> <p>Follow these steps to quickly and easily publish your document to /TR space. It is good to keep differences between the editor's draft on GitHub and version on /TR as small as possible. Echidna makes it possible to self-publish at any time, without having to wait for the webmaster's help.</p> <p>Note that you can't publish First Public Working Drafts using Echidna. That has to go through the normal process.</p> <section id="echidna_setup"> <h3>Setting things up</h3> <p>Ask your staff contact to do the following: </p> <ol> <li> <p>Get a token for your spec from the W3C. You'll need to keep this somewhere safe for when you want to publish the document.</p> </li> <li> <p>Set the <code class="kw" translate="no">w3cid</code> variable inside the document for the editors who will be doing the actual publication.</p> </li> <li>Add a config file for the document on GitHub.</li> </ol> </section> <section id="echidna_publication"> <h3>Actually publishing</h3> <p>Follow these steps:</p> <ol> <li> Check that the GitHub.io Editor's Draft (ED) is valid HTML using the <a href="https://validator.w3.org/">HTML5 validator</a>. </li> <li>Check that all links work using the W3C <a href="https://validator.w3.org/checklink">Link Checker</a>.</li> <li> Run a spell checker over the document. </li> <li>Update the config file for the document so that it lists all images and other dependant files. The config file will be at the top level of the GitHub repo, and usually has the name of the document, without an extension.</li> <li>Go to the <a href="https://labs.w3.org/pubrules/">Pubrules checker</a> and run it against the following URL: <br> <code>https://labs.w3.org/spec-generator/?type=respec&url=https://w3c.github.io/<span style="color: orange">linkToYourSpec</span>/?specStatus=WD&shortName=<span style="color:orange">theShortName</span></code><br> Fix anything that's needed, and rerun the checker until it's ok. You will probably find that the checker complains about not being able to find a dependent file (usually the .css file). That's because the URL above creates a WD version of your main file in a new location for testing, and doesn't copy over the dependent files. You can ignore those messages, but you should double-check that the config file lists all dependent files.</li>  <li>Open a terminal window and run the following Curl statement:<br> <code>curl 'https://labs.w3.org/echidna/api/request' --data 'url=<span style="color:orange">echidnaConfigURL</span>&decision=<span style="color:orange">decisionUrlOnMailingList</span>&token=<span style="color:orange">documentToken'</span></code> </li> <li>Go to the <a href="https://lists.w3.org/Archives/Public/public-tr-notifications/">TR-Notification list</a> to check whether the document was successfully published.</li> </ol> </section> </section> </div> <br style="clear: both;" /> <footer id="thefooter"></footer><script>document.getElementById('thefooter').innerHTML = g.bottomOfPage</script> <script>completePage()</script> </body> </html>