Git Workflow for Adobe Lead Writers

Welcome, Adobe writers!

TIP

Watch this Main Git Workflow video. It’s a couple years old but still accurate for the most part.

See Git and GitHub documentation essentials

Basic editing workflow

How you use Git to edit files depends on several factors:

  • Are other people working on your repo?
  • Is your repo “clean” or still in its post-migration cleanup phase?
  • Are you working on content that can be pushed live immediately or for a future feature release?
  • How familiar are you with Git/Markdown?

If we use Git terms that you’re not familiar with, see Git and GitHub documentation essentials.

Quick Workflow Summary

These steps assume you’ve installed GitHub Desktop and Visual Studio Code, and that you’ve cloned your repo.

  1. Sync - Open GitHub Desktop. Make sure that your local clone is synced with the server. (Don’t work from an old or deleted branch.)

  2. New branch - Create a local branch.

  3. Edit - Create and edit files on your local machine. Save the edited files.

  4. Commit/push to server - In GitHub Desktop, type a “Summary,” commit the changes to your local branch, and then push the local changes to the server.

  5. Pull request - Create a pull request.

  6. Validate - Check validation in Jenkins. Do one of the following:

    • If validation passes, merge to master and delete branch. This triggers a new production job in Jenkins. When that job passes, changes are uploaded for preview on experienceleague.corp.adobe.com.
    • If validation doesn’t pass, edit and commit changes to the branch. This triggers a new validation job. Check to see if your changes fixed the validation issues.
  7. Activate - Wait until the project job finishes, and then run the Jenkins activate-exl job to push the changes live. (If you don’t want to preview content before publish, you can enable auto-activation.)

Detailed Steps

  1. If you have not already done so, clone the repo to work on files locally. See Git Setup: Clone a repo.

  2. Make sure that your cloned repo is up-to-date. (Select master and fetch any updates from the server.)

    Fetch image

  3. Create a branch. (In GitHub Desktop, choose Branch > New Branch.)

    New branch image

    We recommend that you create a branch before you begin editing files, but you can also create a branch after you start editing. Just try to avoid working from an out-of-date branch.

  4. With the branch selected, open the files you want to edit in your editor and make your changes. Save your changed files. (In Visual Studio Code, we recommend that you open the repo folder so that you have easy access to all the files in your repo. If you make changes to multiple files, you can choose File > Save All.)

    VS Code image

    The editing changes are reflected in GitHub Desktop.

    Github desktop changes

  5. In your client, push the edited content upstream to your branch. (In GitHub Desktop, type a Summary name and click Commit to branch. This commits the local edits to a specific branch on your desktop. Then click Publish or Push origin to push the local changes to the server.)

    Github desktop steps

  6. Submit a pull request to the master branch. (One option is to do this in GitHub Desktop by choosing Branch > Create Pull Request. It opens a browser window with the default pull request settings that push to “master”. Then submit the PR.)

    pull request image

  7. Check Jenkins (https://docs.ci.corp.adobe.com) to make sure the content passes validation.

    A pull request is how to get your changes into the main master branch. When you submit a pull request, two validation checks occur. The first one makes sure there are no conflicts between your branch and the master branch. The second one is the Jenkins pipeline validation that makes sure your content is well-formed. See Resolve Validation Errors.

    If there’s a pipeline error, it looks like this:

    validation error image

    Read the summary.txt to see what your errors are. Fix them in your branch before merging to master. Edit the files and commit the changes to your branch. This automatically triggers a new validation job. (See Resolve Validation Errors for details.)

    A successful pass looks like this:

    validation success image

  8. If the content is validated successfully, click Merge pull request > Confirm merge.

    merge image

    Merging into master triggers a Jenkins exl job. Once this job is complete, the changes are uploaded for preview on experienceleague.corp.adobe.com. At that point, you can push the content live (activate) to experienceleague.adobe.com.

    Merging to master also triggers a localization update and syncs the mirror repo on github.com.

  9. Click Delete branch to delete the branch on the server.

    Think of branches as temporary. Once you merge your branch into master, it’s a good idea to delete it. When you start your next round of edits, creating a new branch helps ensure you have the latest stuff.

  10. (Optional) Go back to GitHub Desktop and delete the local branch (with the branch selected, choose Branch > Delete). The master branch is then selected. Deleting the local branch helps avoid working on out-of-date content and keeps things tidy in GitHub Desktop.

    TIP

    If you don’t see the branch you’re looking for from the pulldown list in GitHub Desktop, close and re-open GitHub Desktop, and you’ll see all the available branches again.

  11. When you’re ready (and when the production job is valid and complete), run the activate job in Jenkins to push the content live.

NOTE

When you’re working on a repo alone, you don’t need to work with branches unless you want to work on future features. However, we recommend that you use branching and pull requests as a best practice. Pull requests make it really easy to revert changes.

Other Git Workflows

As you work more with Git, you’ll likely modify the workflow based on various factors.

Direct editing in browser

For simple changes such as fixing typos and changing steps, you don’t need to work from your local cloned files.

IMPORTANT

Don’t make direct changes in the browser AND edit files locally at the same time (or at least not without syncing your local clone properly). You’ll likely create conflicts.

  1. In your browser, open your repo in AdobeDocs.

  2. Locate the file you want to edit.

    TIP

    Open TOC.md, and Command-click any link to open the file in a new tab.

  3. Click the pencil icon, and make your edits.

    edit icon

  4. Make your edits. When you finish, do one of the following:

    • (Recommended) Select the option to create a branch, and then click Propose file change. You’ll then submit a pull request, which you can merge (preferably after the validation check).
    • (Be careful!) Click Commit changes to make the changes directly to master.

    direct browser edit

  5. The next time you work on your local clone files, remember to sync your cloned files with the master.

Persistent branch

In this article, we emphasize creating and deleting branches as you work. However, once you become more experienced with Git, consider using a long-running branch model. For example, you can create a branch called “staging” or a branch with your name. The danger of using a persistent branch is that it can get out of sync with the master. But there’s an easy fix for that if you’re mindful.

To keep the persistent branch in sync with master, create a pull request that merges from master to the persistent branch whenever you’re ready to edit.

pr from master

Pull request from master to stage to keep stage in sync with master

Although you can use GitHub to create a pull request from master to your branch, a quick way to merge from master to your branch is to use Visual Studio Code.

  1. Press Command+Shift+P to open the command palette.
  2. In the search field that appears at the top of the screen, type git merge.
  3. Select the item Git: Merge Branch from the drop-down menu.
  4. Select master from the drop-down menu.
  5. Push the changes from your local branch to the server.

vsc merge master

The merge occurs and your branch is now in sync with master.

Direct clone

After you clone your repo, you can make edits and commit them directly to the master without creating a branch. This workflow is not recommended, but it can be useful in a few situations, such as during a migration cleanup when you’re not worried about introducing validation errors and you’re the only person working on the files.

Creating articles

When you need to create a new Markdown file in Git, follow these steps.

  1. In Github Desktop, make sure that your cloned repo is synced with master, and create a branch.

  2. In Visual Studio Code, open the folder of your cloned repo.

  3. Choose File > New, and then create a new file.

    TIP

    Feel free to copy content from the sample Markdown file to start your file.

    new file image

  4. Add the appropriate metadata at the top of the file.

  5. Use the proper Markdown syntax to write the article.

  6. Save the article with a .md extension in the appropriate Git folder.

    Use all lowercase letters, no spaces, and hyphens instead of underscores.

  7. Add the file to the appropriate section of the TOC.md file.

    new file image

  8. In GitHub Desktop, commit the changes to your branch and push them to the server.

  9. Create a pull request, and follow the standard workflow to validate, preview, merge, and activate the content when you’re ready.

See also:

On this page