Git workflow for Adobe lead writers

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

New branch - Create a local branch. (You can also create a new branch after you make edits. You have the option of committing your edits to the new branch.)

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

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.

Pull request - Preview and create a pull request.

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

• If validation passes, merge to main and delete branch. This triggers a new EXL job in Jenkins. When that job passes, you’ll get a Slack notification with details for previewing and publishing.
• If validation doesn’t pass, edit the necessary files in your branch and commit changes. This triggers a new validation job which you can track in the Git PR.

Activate (if live) - Wait until the project job finishes, and then run the Jenkins activate-new job to push the changes live immediately. (If you don’t manually activate, edits go live in the next 2-hour window.)

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

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

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

We recommend that you create a branch before you begin editing files, but you can also create a branch after you start editing. Select the option to bring the changes to the new branch (don’t leave them associated with main).

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.)

The editing changes are reflected in GitHub Desktop.

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.)

Preview and submit a pull request to the main branch. (One option is to do this in GitHub Desktop by choosing Branch > Preview Pull Request.

If your changes look good in preview, click Create Pull Request (otherwise, cancel and keep editing).

Creating a pull request opens a browser window with the default pull request settings that push to “main”. Then submit the PR.)

Check to make sure the content passes validation.

A pull request is how to get your changes into the main main 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 main 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:

Read the validation summary in the Git PR to see what your errors are. Fix them in your branch before merging to main. 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:

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

Merging into main triggers a Jenkins exl job. A summary of this job appears as a Slack notification.

Once this job is complete, the changes are uploaded for preview on experienceleague.corp.adobe.com. If auto-activate is enabled, your changes will go live within the next two hours. You can also publish your content immediately on experienceleague.adobe.com. See Publish content.

Click Delete branch to delete the branch on the server.

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

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

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

In your browser, open your repo in AdobeDocs.

Locate the file you want to edit.

Click the pencil icon, and make your edits.

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 main.

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

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

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

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

Add the appropriate metadata at the top of the file.

Use the proper Markdown syntax to write the article.

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

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

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

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

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