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

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. Do one of the following:

• If validation passes, merge to main and delete branch. When that job passes, you’ll get a Slack notification with links to published articles.
• 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.

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

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 a GitHub action that makes sure your content is well-formed. See Resolve Validation Errors.

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

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

Once this job is complete, the changes are uploaded to EXL. For information about publishing and preview content, 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.

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

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.