GitHub Workflow

The work-flow illustrated here is the way we should handle content and source in the master branch of the ajax-docs repository.

Minor Changes

Minor changes like fixing typos, grammatical corrections can be directly pushed in the master branch, without making a Pull Request, or 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 sucessful (Pull with Re-base);

6. Push your commit to GitHub (Pushing Commits)

7. Rebase your changes into the vNext branch so everyone works with the latest content (Merging Changes from one Branch to Another)

Major Changes

Major changes are more complex fixes, re-structuring articles 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 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 piblished branch in GitHub.

   You should also rebase your branch from its base branch before you start working. This will ensure it is always up to date with its source branch and you work with the latest version of the content.

5. When the task is done, make sure the branch is synced with the parent branch (usually master) (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.

vNext

This section treats working with feature changes, i.e., documentation that should not be live immediately, but with the next official release of the UI for ASP.NET AJAX suite. For example, if you are working on the documentation of featureX that should go live with Q1 2016 and it is still the autumn of 2015, here is the process you should follow.

1. Make sure the vNext branch exists. It should bear the name of the next official release (e.g., Q12016, Q32016, Q22017). Make sure it is at the head of the master branch.

2. Checkout the vNext branch (e.g., use git checkout Q12016).

3. Create a branch that describes the feature you will be documenting (e.g., git checkout -b featureX).

4. Publish the branch(es), commit your changes, etc.

5. Make sure to rebase your branch from its base branch before you start working the next time. Make sure the base branch is up to date with upstream to ensure you will not delete someone's work (i.e., pull and rebase it first).

6. When you are done, open a Pull Request to merge your work into the vNext branch and ensure you have already rebased it from vNext.

The goal is to ensure that the vNext branch is always up-to-date with the latest content that is live from the master branch (see Minor Changes which ensures vNext is updated) and that the history of all the branches in the repo is linear.

When it is time to release the documentation, vNext will be merged into master which should not have conflicts and will not need review. This can be done with or without a Pull Request.

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 (this can be the feature branch for a set of articles that stems from the vNext 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 (be it vNext or master).

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 that is to be improved and specify the branch

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

Working with a reviewer in GitHub:

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

• If there are only minor issues (typos, commas, etc.) the reviewer will directly commit to the specified branch (denoted in the Issue or the compare branch in the Pull Request). Who will merge this branch is to be determined in the Pull Request but it is usually the writer.

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

• If work is done directly in the master/vNext branch (e.g., a reviewer is working on an Issue), the reviewer will create a new branch stemming from the specified branch, apply changes/suggestions/comments there and open a Pull Request where the standard workflow applies.

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