GitHub Workflow

The work-flow illustrated here is the way we should handle content and source in the ajax-docs repository. For styling the content you can follow the Style Guide.

There will be two branches present at all times - master and prodiction. The master branch will contain all content. The production branch will contain the content that is live. Any new content should be added to master first. If the new information should go live it should be crerry-picked to production.

Workflow Overview

1. Decide that something needs an update. Or new information should be added. (Every journey begins as an idea :) )

2. Add the new information to master. The change can be minor or major. If the content you have added should go live with the next major release (e.g. Q1, Q2, Q3) - you are done, else read on. Note that Service Packs are not major releases.

3. If you are reading this, then the change should go live as soon as possible. The commits that should be live have to be cherry-picked and added to production branch.

Minor Changes

Minor changes like fixing typos, grammatical corrections can be pushed in the master branch directly, without creating a new branch.

1. Make sure you are working with the latest changes pulled from GitHub (Pull with Re-base);

2. Implement the required changes;

3. Stage the affected files (Stage Files);

4. Commit the changes locally (Committing);

5. Again, pull any changes from GitHub to make sure that the push will be successful (Pull with Re-base);

6. Push your commit to the master branch on GitHub (Pushing Commits)

7. If the changes should go live immediately - cherry-pick them and add them to production. (Cherry-picking);

Major Changes

Major changes are more complex fixes, restructuring articles, adding new article(s), etc. Working on such tasks should be done in a branch, that later to be used for a Pull Request.

1. Make sure you are working with the latest changes pulled from the master branch on GitHub (Pull with Re-base);

2. Create and Checkout branch with a meaningful name (Create new Branch and Checkout Branch);

   Tip: You can use one command for both actions git checkout -b MyBranch

3. Publish the branch to GitHub (Push Branch to GitHub);

4. Changes made on the branch can be done in several commits (as much as you need, in order to have proper history/backlog) (Push Commits to Branch).

   If there are other collaborators working on this branch, you should periodically pull and push changes to the published branch in GitHub.

5. When the task is done, make sure the branch is synced with the master branch (Syncing Changes from the Remote's master Branch);

6. Push any additional changes derived from the master branch (Push Commits to Branch);

7. Initiate a Pull Request from GitHub (Pull Requests).

   Important: GitHub will alert you if the Pull Request is clean. If this is not so, go back to your local repository and make sure any conflicts are locally resolved.

8. If you want your changes to go live cherry-pick them and add them to production. (Cherry-picking);

Article Review

Generally, articles should be reviewed by another person before going live to improve their quality.

For new articles that have not existed yet, it is best to create a branch.

It is recommended that articles pass through peer review by your team before they are published and/or sent for copy editing by a single person. If this is impossible, it is still good to have the peer review after the copy-editing phase, and if there are changes they should be copy-edited again.

Always keep the Style Guide in mind when writing/editing/reviewing.

Here follows a general description of the processes.

Once you are done writing, you should:

1. Get a Peer Review from your team, if possible, and apply the changes you agreed on.

2. Open a Pull Request and assign it to the person who will review it (e.g., copy editor).

3. When you are done with the discussion, rebase your change/feature branch from the source branch and merge it to the base branch.

4. In most cases you can then delete the change/feature branch afterwards.

For articles that exist live and need to be improved:

1. open an Issue in GitHub

2. Link the article/s that is to be improved and specify the branch

3. Assign the Issue to the reviewer/copy-editor.

Working with a reviewer in GitHub:

• Typically work process should be handled in Pull Requests. That said, all changes that the copy editor does are committed directly in the branch of the Pull Request.

  • When the reviewer is done with the Pull Request, they add a comment in the Pull Request Conversation tab to indicate they have completed work and the request can be merged by the author.

• When an Issue item is assigned to copy editor. They create a new branch stemming from the specified branch. When finished applying changes/suggestions/comments Pull Request should be opened. All changes should be again committed in the same branch.

  • Branches created by the copy editor should have a meaningful name:
    • When a single file should be edited it should follow this pattern — [Control]-[filename]-[info];
    • For multiple files, this one — [Control]-[info];
    • If the article is not control specific — Common-[info].
  • Team members must monitor the Pull Requests section and quickly deal with new ones.
  • The Issue is to be closed after the Pull Request is merged.

• If a Pull Request must be merged so it can go live, an issue must be opened if work with reviewer needs to continue.

• If there are many issues (e.g., with the Style Guide adherence, sentences/paragraphs not making sense, etc.), the reviewer/editor may not fix them, but leave a comment for the writer to fix them.

• Important: Make sure to look for reviewer/editor comments in the content, they will usually be something like <Comment: comment goes here> and make sure to delete them before the article goes live (after applying any necessary changes, of course).