Contributing & Making Changes

As you make changes to the help topics repository you must make sure to follow a few guidelines in order to ensure the commit history remains clean. In order to keep the history as clean as possible you always want to apply changes to the lowest applicable version and merge up, never the other way around. This guide details how to make different types of changes to the repository while keeping a clean commit history.

What's Your Role?

Depending on whether you are a repository administrator or not the steps you take will likely differ.

Role	Description
Individuals	Team members (and those outside the organization) that do not have administrator rights are expected to fork the repository and submit pull requests for any changes. Important: You must make changes to the lowest applicable branch of the repository!
Administrators	Product leaders, those developing documentation tools and the like have rights to commit directly to the repository.

Quick Reference

Action | Description | | | --- | --- | --- | --- | --- | Change to highest branch only | Applies a change only to the latest branch | Individual | Administrator Change to multiple branches | Commit change first to lowest branch, then merge change to higher branches. This applies an identical change to each branch while preserving a clean commit history | Individual | Administrator Change to lower branch only** | Commit change to lower branch(es), merge an empty commit to higher branch(es). Applies a change to lower branches while preserving a clean commit history. | Individual | Administrator

^* You must designate intended/applicable branches in the pull request names and/or descriptions when making changes to lower version so they get merged up. See examples below.

Individuals

Change to Highest Branch

The process here is the basic GitHub workflow; you create a pull request that applies to only the highest (default) branch.

Change in Multiple Branches

This process describes the steps you need to execute if you want to commit an identical change to multiple branches in the repository including the latest.

Steps

1. Commit change first to lowest applicable branch
2. Create a pull request to same branch in the Help Topics repository describing the range of branches this change is intended for

Example

First, commit your change to the lowest branch applicable to your change. Next, create a pull request.

Note: Make sure to note in the comments the branch(es) that are affected by the change.

Change to Lower Branch Only

This process describes how you would commit a change that applies ONLY to lower branch(es).

Steps

This process is identical to Change to multiple branches; you create a pull request to the lowest applicable branch and submit a pull request with the proper description to let administrators know where to merge the changes.

---

Administrators

Change to Highest Branch

The process here is the basic GitHub workflow; commit a change (as an administrator) that applies to only the highest (default) branch.

Example

You need to make a changes to topics for only the latest version (assuming 15.1 is the latest version). First you commit the change to 15.1 and push the changes to the server. The 14.1 and 14.2 branches are left unaltered.

[15.1]> git commit -m "Update links for igGrid MVC topic"
[15.1]> git push

Change in Multiple Branches

This process describes the steps you need to execute if you want to commit an identical change to multiple branches in the repository including the latest.

Steps

1. Commit change first to lowest applicable branch
2. Merge from previous branch to the next up to the highest branch - do not cherry-pick the initial request, just do normal branch merges to keep the linear history.

Example

You need to make a change to a topic and it needs to apply to all branches (assuming 15.1 is the latest branch). First, you commit your change to the 14.1 branch. Next, you merge the commit from 14.1 to 14.2. Finally, you merge the change from 14.2 to 15.1.

[14.1]> git commit -m "Update links for igGrid MVC topic"
[14.1]> git push

[14.2]> git merge 14.1
[14.2]> git push

[15.1]> git merge 14.2
[15.1]> git push

Change to Lower Branch Only

This process describes how you would commit a change that applies ONLY to lower branch(es). To preserve the liner history and comparability the very

Steps

The merge process is as follows:

1. Merge pull request or commit changes first to lowest applicable branch
2. Merge commit to next target branch (if available)
3. Initiate merge on the next branch that is not a target (by using the merge --no-commit --no-ff command)
4. Discard unwanted file changes
5. Commit the empty merge (now only for history)
6. Merge to highest branch as usual (if needed)

Example

You need to make a changes to topics from all versions excluding the latest version. First you commit the change to 14.1 and then merge the change to 14.2. Next, you merge just the history to 15.1 by discarding all changes in the commit:

[14.1]> git commit -m "Update links for igGrid MVC topic"
[14.1]> git push

[14.2]> git merge 14.1
[14.2]> git push

[15.1]> git merge --no-commit --no-ff 14.2

# !! IMPORTANT !! discard all file changes from the commit
git checkout HEAD -- .

# commit the merge without the changes
[15.1]> git commit
[15.1]> git push

Explanation: The merge command will act as usual but stop before committing the changes. At that point there should be an active merge in progress and unstaged file changes you can discard via checkout - the HEAD resolves to the original version and the . path will match all files. You should be left with no changes, but active merge you can conclude with commit.

You're probably thinking, "This seems unintuitive and unnecessary. Why should I commit empty changes?" You are correct, this is strange but unfortunately necessary to keep the commit history clean in order to make it easy to publish other changes later made to the repository.