Work with GitHub Pull Requests and Issues

Users—both internal and external—can use the Log an issue and Edit this page options in experienceleague.adobe.com articles.

log issue and edit page settings

Whenever a user creates a pull request on the public GitHub.com mirror, a member of the SSE team will evaluate the proposed changes and push the pull request to the git.corp.adobe.com repo, if appropriate. A member of the writing team should then manage the pull request.

IMPORTANT

DO NOT merge pull requests on github.com. Instead, make the changes on git.corp.adobe.com (either by copying the PR to Corp and merging it or by simply making the edits). Then close the pull request on github.com without merging.

For details about how you or other users can log issues or edit pages on GitHub, see the Adobe Contributor Guide.

Summary of what Adobe writers should do

Enterprise Git (git.corp.adobe.com/adobedocs) and Public Git (github.com/adobedocs) are different environments that require different log-in accounts and have different configuration settings.

  1. Sign up for GitHub.com (different from git.corp.adobe.com)

    If you don’t already have a GitHub account, go to https://github.com/join. We recommend that you use your Adobe email address.

  2. Sign up for GitHub notifications

    Go to your public repo on github.com and choose Watching. You’ll get notifications when users log issues or submit pull requests.

  3. Contact the SSE team to be added as an admin to the public repo. Let us know your github.com account name.

    When we add you as an admin, you’ll be able to close issues and pull requests in your public repo.

Sign up for GitHub notifications

Keep in mind that notification settings for git.corp.adobe.com/adobedocs and github.com/adobedocs are different and require different log-in accounts and separate configurations.

IMPORTANT

In order to get notifications of logged issues and pull requests from the public git repositories, you must enable notifications on your public repository.

You can enable notifications so that you get an email message whenever anyone logs an issue or submits a pull request for the public docs on github.com.

  1. Go to your repo on GitHub.
  2. From the Watch (or Unwatch) pull-down menu, choose Watching to receive notifications.

watch menu image

By default, you don’t get notifications whenever you make changes to the repo, just when other people do.

NOTE

Check your junk or spam folder if you aren’t getting notifications when others add pull requests or issues to the GitHub repo.

If you want different access rights, such as the ability to close issues or pull requests on github.com, contact the SSE team.

Monitor incoming contributions

In order to keep track of all incoming contributions:

Authors should watch their repo, both corp (git.corp.adobe.com) and public (github.com). See Sign up for GitHub notifications.

The workflow for managaging pull requests differs for corp and public, so make sure that you have a method for identifying public GitHub.com requests. For example, in email notifications, Corp notifications include a colored icon, whereas public GitHub.com requests include a black-and-white icon.

notification icons

React to the contributions as they come in:

  • For logged issues, make any necessary change to the documentation and reply to the issue as appropriate.
  • For public pull requests, work out a process with the SSE team. By default, an SSE team member should evaluate the pull request and copy it from the public repo to the corp repo. Depending on your team size and level of expertise, you might want to change this workflow. Please contact an SSE team member (usually Bob or Alva) and ask them about copying public PRs.
IMPORTANT

When you receive notification of a pull request on github.com, DO NOT merge the pull request in the public repo. That creates a temporary change on github.com that will be blown away with the next commit to master on git.corp.adobe.com. It’s a one-way flow from Corp to Public. Instead, ask the SSE team to copy the PR to git.corp.adobe.com, merge the PR on Corp, and then close the issue on github.com.

Always make your edits in Corp, which is the source of truth. Corp edits flow into the Public mirror automatically. Edits to the Public mirror are meaningless, and will be wiped away with the next commit to Corp master.

If you work on a project with multiple team members, consider setting up a triage system. For an example, see the AEM team’s Managing Contributions wiki workflow.

GitHub > Jira workflow

The AEM team created an automation process to auto-generate JIRA tickets from any issue logged in the GitHub.com repo. This workflow allows support operators to use the GitHub Log an issue feature as their point of entry in reporting documentation issues.

See DocBug Automation Process

Contact the SSE team if you’re interested in a similar implementation.

Copy GitHub pull request to Git Corp (SSE team)

This process is for the SSE team or for anyone else who wants to copy a pull request from GitHub to Git Corp. If you want to copy pull requests yourself, let the SSE team know so that we don’t duplicate efforts.

  1. Open GitHub Desktop (or your client of choice) and make sure that your local clone is up-to-date.

  2. Open Terminal or your favorite command-line tool.

  3. In Terminal/command-line tool, go to the repo in your local GitHub directory. Example:

    cd Documents/GitHub/target.en

  4. Use the following command lines to create a branch on your local drive and push the changes from GitHub to that branch.

    cd Documents/GitHub/<repo-name>
    git checkout -b <user>-<branch> master
    git pull https://github.com/<org>/<repo-name>.git <branch>
    

    Replace <reponame>, <user>, <branch>, and <org> with information from GitHub pull request. The <org> variable depends on whether the GitHub pull request is from a fork (more common) or from a branch (internal Adobe users with write access). If there is a branch, use AdobeDocs for <org>. If there is a fork, use the <user> value. See the examples below.

  5. Go to GitHub Desktop, select the newly added branch, and push the branch to the server.

    publish branch image

  6. Create a pull request.

  7. (Writer) Validate, edit (if necessary), and merge when ready.

  8. (Writer or SSE) Close the pull request on the GitHub repo with thank you comment.

Example

Suppose you have the following pull request.

In this example, the mtalbot29 user created the pull request in a fork (also mtalbot29) in the patch-2 branch in the target.en repo.

cd Documents/GitHub/target.en
git checkout -b mtalbot29-patch-2 master
git pull https://github.com/mtalbot29/target.en.git patch-2

Follow the steps above to complete pull request and merge into master.

Create a public git mirror (SSE team)

Before you go public with a repository, you need to create a public git mirror repository that contributors can work with. This is the repository that is linked to for Edit this Page or Log an Issue in the right rail of every article.

In addition, after creating the public mirror, in the metadata of the guide that you’re launching, you need to switch the address from the corporate git to the public git.

Currently, Alva has access to the Jenkins instance to create new mirrors. For access, please reach out to Hiren Shah.

To create a public git mirror repository:

  1. Open three tabs with the following:

    • https://adobedocs.ci.corp.adobe.com (log in with LDAP ID)
    • https://github.com/AdobeDocs/name-of-repo.en(log in with your public git user)
    • https://git.corp.adobe.com/AdobeDocs/name-of-repo.en
  2. Navigate to your repository in git corp. Copy the name of the repository.

  3. Open public git and paste the name into the search area. This ensures that you do not have that mirror already created.

  4. If it is not created (most likely), click New and add the following information:

    • In repository name, copy the name from the corp git account, for example, debugger.en.
    • Copy the description of the repo from the corp git account.

    create repository

  5. Click Create repository. You have created your public repository. Now you need to connect the corporate and public repositories.

  6. In https://adobedocs.ci.corp.adobe.com/, click New Item.

  7. Create a new item with the same name as the repository (best to copy it from corp git) and select Freestyle project.

    new item

  8. Scroll down the page to the Copy from area and pick the name of another repository that already has a public git mirror such as analytics.en.

    copy repository

  9. Click OK.

  10. Scroll down to the code. Select the code and copy it into a text editor like VSCode. You need to replace all instances (5) of the old repository name with the current repository name. (for example, you’ll substitute debugger.en for analytics.en)

  11. Search for the name and replace it. Copy this code and replace all the code that was there.

  12. Remove line 43, which starts with sh git pull. (Keep this line safe as you’ll need to add it later - I copy it from the VSCode file) This line needs to be removed the first and only the first time you set up the mirror. The reason is because there are currently no pull requests on the public repository, so this will cause an error.

  13. Click Save.

  14. Click Build Now. The build runs. If all goes well, it will be successful.

  15. Navigate to the public git repository and make sure the content is there and matches what is on git corp.

  16. Go back to Jenkins and click Configure.

  17. In the code, add line 43 back in and save your changes.

  18. Click Build Now.

Your public mirror is set up.

After you have set up your public mirror and before launch, in metadata.md (or TOC.md) change the URL from the corp git to public git.

On this page