Welcome, Adobe writers!
Watch this Main Git Workflow video. It’s a couple years old but still accurate for the most part.
How you use Git to edit files depends on several factors:
If we use Git terms that you’re not familiar with, see Git and GitHub documentation essentials.
These steps assume you’ve installed GitHub Desktop and Visual Studio Code, and that you’ve cloned your repo.
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.
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 - Create a pull request.
Validate - Check validation in Jenkins. Do one of the following:
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.)
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 master 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. Just try to avoid working from an out-of-date branch.
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 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.)
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:
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:
If the content is validated successfully, click Merge pull request > Confirm merge.
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
Merging to master also triggers a localization update and syncs the mirror repo on github.com.
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.
(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.
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.
When you’re ready (and when the production job is valid and complete), run the activate job in Jenkins to push the content live.
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.
As you work more with Git, you’ll likely modify the workflow based on various factors.
For simple changes such as fixing typos and changing steps, you don’t need to work from your local cloned files.
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.
In your browser, open your repo in AdobeDocs.
Locate the file you want to edit.
Open TOC.md, and Command-click any link to open the file in a new tab.
Click the pencil icon, and make your edits.
Make your edits. When you finish, do one of the following:
The next time you work on your local clone files, remember to sync your cloned files with the master.
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.
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.
The merge occurs and your branch is now in sync with master.
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.
When you need to create a new Markdown file in Git, follow these steps.
In Github Desktop, make sure that your cloned repo is synced with master, and create a branch.
In Visual Studio Code, open the folder of your cloned repo.
Choose File > New, and then create a new file.
Feel free to copy content from the sample Markdown file to start your 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.