Git and GitHub documentation essentials

Git has a unique contribution workflow and terminology to support its distributed model. For instance, there is no file locking that is normally associated with check-out/check-in operations. Git allows changes to be resolved at an even finer level, comparing files byte by byte.

Overview

As a contributor to Adobe documentation content, you can interact with multiple tools and processes. You can work in parallel with other contributors on the same project, potentially the exact same content, even at the same time. This is all enabled through Git and GitHub software.

Git is an open-source version control system that allows collaboration. Multiple contributors can work on files that live in repositories.

GitHub is a web-based hosting service for Git repositories, such as those used to store https://experienceleague.adobe.com content. For any project, GitHub hosts the main repository, from which contributors can make copies for their own work.

Git Glossary

Git is very powerful but can take some getting used to. Here is a breakdown of the important terms you will encounter as you begin to use Git.

GitHub - The hosted version of git that is accessible in the cloud which acts as the central control for our documentation.

Repository - A “repo” is one grouping of documentation. These are usually project-specific.

Local clone - The local copy of a repository each has on his/her machine. Every author starts by cloning the repository on GitHub. Do not confuse cloning with branching or forking.

Commit - A set of changes made that is saved to git. This can be one line to one file or hundreds of lines across hundreds of files. A commit should be a logical, incremental step that you want to save. Commits can not be undone and serve as a record of the evolution of your documentation progress. Because they are permanent, they can be used to track changes as even recreate the entire repository back to a specific point in time.

Branch - A branch is a variation of the documentation or a work-in-progess work space. When making a change, a branch from the master is created and in this branch is where the changes are made. Each author will have his/her own branch with the possibility to create additional branches as necessary. Do not confuse branching with cloning or forking.

Master - The master branch represents the current, official state of the documentation within a repository. Only master content is published. Changes can be made to master, but generally changes should be made to a branch, which is then merged to master through a pull request.

Merge - When a change is finished on a branch is is merged back into the master. One branch can be merged into any other branch as well to unite different changes. Because master is just another branch, the mechanism works the same way.

Push - When changes are ready locally, they can be pushed to GitHub. Pushes should be to a branch and not to the master.

Pull Request (PR) - The request to merge content from one branch into another branch. For example, to merge changes from a branch to the master branch, a pull request is made. This is a formal request to pull the changes into the master branch. Anyone can create a PR, but only authors can approve a PR. Once a PR is approved, it can be merged to master.

Pull - Because GitHub is decentralized, changes can be made to the master while you are working locally on your own branch. To get the latest state of the repository, you pull these changes down to your clone.

Fork - Forks are not used in our internal documentation processes. Do not confuse them with cloning or branching.

Mirror - Only Adobe employees can access our authoring content on git.corp.adobe.com/adobedocs. However, we want the public to be able to make Git-based contributions. To do this, we create a mirror of our repos on github.com/adobedocs so that our users can log issues and submit page edits as PRs.

These terms are explained in more detail below.

AdobeDocs on GitHub

Contributors interact with Git to update and manipulate repositories at both the local and GitHub levels:

Key Concepts

Here are some Git definitions and information.

Master branch

For AdobeDocs repos, the master branch is our production branch. When changes are committed to the master branch, either through a merge pull request or direct commit, at least three things occur:

  • A validation check is made.
  • If validation check passes, content is pushed through the pipeline for staging on experienceleague.corp.adobe.com, where it can then be pushed live to experienceleague.adobe.com as a separate action.
  • Changes are submitted to loc workflow for machine translation.

You’ll likely see the term base branch in GitHub. The base branch refers to the main branch in the repo, which is the master branch by default. However, in some cases, people make a different branch, such as staging, the base branch.

Branching, forking, and cloning

When you’re working on new features for an upcoming release, you don’t want to edit the master branch directly. It would be too easy for someone to push those changes live accidentally. Instead, the recommended workflow is to branch the repo, and then push the changes upstream into master when you’re ready.

Branching

A branch is a parallel version of a repository. It is contained within the repository, but does not affect the primary or master branch, allowing you to work freely without disrupting the live production version. When you’ve made the changes you want to make, you can merge your branch back into the master branch and publish your changes.

branching image

For best results, treat branches as temporary workspaces. As soon as you submit a pull request from a branch and merge it, delete the branch. It’s easy to create a new branch, and you’ll know when you create it that it’s in sync.

Cloning

A clone is a copy of a repository that lives on your computer instead of on a server. With your clone you can edit the files in your preferred editor and use Git to keep track of your changes without having to be online. It is, however, connected to the remote version so that changes can be synced between the two. You can push your local changes to the remote to keep them synced when you’re online.

Cloning diagram

Forking

Forking is NOT necessary for lead writers and core collaborators. Branching and cloning is all you need. This section if simply for your information.

Forking ice hole

A fork is a personal copy of a repository that lives on your GitHub account. For example, when you fork the Analytics repo, you duplicate the AdobeDocs/analytics.en repo onto your personal GitHub server space, such as bbringhu/analytics.en. Like branching, forking is a way to make changes in a separate environment and then submit them as a pull request when you’re ready.

Pull requests

A pull request lets you check changes in from your branch to the master. (Some people think it should be called a “push request.” It’s a pull request because you’re asking the person who controls the master branch to pull in your changes.)

When you submit a pull request (PR) to the master branch, the content is validated in two ways: (1) to make sure there are no conflicts between the branch and master and (2) to ensure the Markdown syntax is valid for the Jenkins pipeline. See Resolve Validation Errors.

See Manage pull requests below.

Public Mirror

The source of truth for AdobeDocs is on our corporate server at git.corp.adobe.com/AdobeDocs. However, each repo has a public-facing mirror on github.com/AdobeDocs so that users, both internal and external, can submit edits as pull requests or log issues directly in help.

See Work with GitHub pull requests and issues.

Directory organization

A project’s default/master branch serves as the current version of content for the project. The content in the master branch—and branches created from it—aligns with the organization of the article topics. Subdirectories are used for organizing content and image assets.

You can typically find a main help directory off the root of the repository. The articles directory contains a set of subdirectories. Articles in the subdirectories are formatted as Markdown files that use an .md extension.

Within the root of this directory, you can find general articles that relate to the overall service or product. And typically, you can then find another series of subdirectories that match the features/services or common scenarios.

See User Guide Setup for details.

Manage pull requests

A pull request provides a convenient way for a contributor to propose a set of changes that will be applied to the master branch. The changes (also known as commits) are stored in a contributor’s branch, so GitHub can first model the impact of merging them into the master branch. A pull request also serves as a mechanism to provide the contributor with feedback from a build/validation process, the pull request reviewer, to resolve potential issues or questions before the changes are merged into the master branch.

pull request example

  • To merge the changes, click Merge Pull Request > Confirm merge. You can then delete the branch associated with the pull request if desired.
  • To edit the changes before merging, either click one of the change descriptions (circled in the image above), click the pencil icon, and make the changes you want. You can also go to the branch and make changes to the selected file. When you commit the changes to the branch, a new validation job is kicked off.
  • To reject the changes, click Close pull request at the bottom of the pull request page. You can also delete the branch associated with the pull request.

For information about managing pull requests that you get from customers on github.com/adobedocs, see Work with GitHub Pull Requests and Issues.

Change Git settings

Make sure that you’re receiving notifications properly and that your repo settings are right for your team.

Receive Git notifications and change Git settings

You can enable notifications so that you get an email message whenever anyone submits a pull request, commits to master, or logs an issue in the repo you’re working on.

  1. Go to your repo on Adobe Git.

  2. From the Watch (or Unwatch) pull-down menu, choose Watching to receive notifications.

    watch menu image

Now whenever a conversation is started on this repository such as regarding a pull request or an issue is logged, you will receive an email. By default, you don’t get notifications whenever you make changes to the repo, just when other people do.

If you don’t wish to receive emails but would rather receive notification within the GitHub website itself, you can change your settings.

NOTE

These instructions are for receiving Git notifications on our internal git.corp.adobe.com repos. To set up notifications for public mirrors on github.com/adobedocs, see Sign up for GitHub Notifications.

Change Git permissions

You can also change settings in your repo to protect the master branch and give other people permissions.

  1. Go to your repo on Adobe Git.

  2. Click Settings.

  3. Click Collaborators & teams to change permissions for team members.

  4. Click Branches to change settings for the master branch.

    branch permissions

    Contact the SSE team for additional information and guidance with permissions.

For information about the public mirror on github.com/adobedocs, see Work with GitHub Pull Requests and Issues.

On this page