Github for editors
This page is for people who edit our documents on github. To just comment on our documents see Github for members
Overview
Branches and pull requests are essential to edit GitHub document. They help us work on documents together and check our work before putting in the final draft.
note most of this content is from github docs, but I cut information that we dont use .
Terms
Terms for our main process
Repository. Repositories are like a project's folder. A repository contains all of a project files (including documentation), and stores each file's revision history. Coga has its repository at https://github.com/w3c/coga.
Branch . We use branches to safely add content. A branch is an isolated environment that starts as a copy of the main branch. It allows you to add or edit content, add sections or change the structure without affecting the main branch being affected.
When the content in the new branch is ready open a pull request to check it and put it in the main branch.
A word of warning. If people are working on the same section in different branches, we can get a conflict when we merge it back in. SO use branch for specific changes, and make sure no one else is working on a different branch on the same section. Merge back in at every convenient place.
See creating-a-branch on github docs for instructions to make a branch.
Main branch (also called default branch) The main branch or default branch is the branch that GitHub displays when anyone visits your repository. It is also the first branch in the repository. The default branch is also what Git checks out or uses when someone clones the repository.
To edit document online
- Go to your branch, and find the file.
- Click the file that you want to view.
- In the upper-right corner of the file view, click edit (the pencil icon).
You can check how looks in real life using githack see https://raw.githack.com/ . This will make an html live page for you to see and check that everything works correctly. Note it can take time to refresh.
Pull request. A pull request is a request to merge a branch into another branch (usually the main branch). In a pull request, we can see the changes and review and discuss the them before they integrate the changes into the main codebase. Pull requests display the differences, or diffs, between the content in the branch and main branch.
Please use our template pull-request-template.md in our base directory. (I think this happens automatically. ). It will ask you if you have tested that the format is ok. You can see how your file will look, and test it, by loading it into https://raw.githack.com/.
See how to make a pull request on github docs.
Merge . Once your pull request is approved, merge your pull request. This will merge your branch so that your changes are in the default branch.
Delete After you merge your pull request, delete your branch. See deleting and restoring branches in a pull request in github docs.
More Terms
These terms are often used when making a desktop version of our repository. I have based this process on the desktop version. I think you can download it at download github desktop . Note to edit files you can use any html editor including notepad. Just make sure you save it in the correct format!!! Do not use word or any editor that adds not conformant characters.
Clones A clone is a copy of a repository that lives on your computer instead of on a website's server somewhere, or the act of making that copy. When you make a clone, you can edit the files in your preferred editor and use Git to keep track of your changes without having to be online. The repository you cloned is still connected to the remote version so that you can push your local changes to the remote to keep them synced when you're online.
Pull Pull usually is updating your local version with the online version. A pull fetches in changes and merges them in. This is often if you are working on your desktop version and someone has merged in different changes online to the main branch. You may want these changes on your desktop clone. So you will pull in those changes to your local copy. It is a good idea to do a pull before starting work on you desktop clone!
Commit A commit, is an individual change to a file. You make a commit to save your work. Make sure you commit to the branch you should be working on or you will lose your work.
Push (sometimes called Fetch). When you push, you send the committed changes in your local repository to the remote repository on GitHub. You must commit and push your the changes to GitHub to the branch you are working on, if you want others to see and use your changes!
Before pushing changes, you should PULL (update) your local branch to include any commits that have been added to the remote repository. If someone has made commits on the remote that are not on your local branch, GitHub Desktop will prompt you to fetch the new commits before pushing your changes to avoid merge conflicts. For more information, see pushing changes to github from github-desktop .
Fork (less important) This is better to avoid! A fork is a personal copy of a repository that lives on your account. Forks allow you to freely make changes to a repository without affecting the original repository. You can also make a pull request in the original repository when you are finished with your changes.
Also see getting started with github-desktop
Examples of ways to use github
GitHub.com, with GitHub Desktop, in GitHub Codespaces, on GitHub Mobile, and when using GitHub CLI.
Further reading Video instruction of GitHub in W3C: https://w3c.github.io/wai-gh-training-2015-06-29/