Build Process Docs

This doc represents the steps for submitting a PR to this repo.

• Make any code changes in their respective, original source files under the /lib directory, and then the final distribution source files can be magically rebuilt.

• The build number needs to be incremented in the /offline-editor-js/package.json and /offline-editor-js/samples/package.json files. Make sure to use the pattern vX.X.X. Include the final dot-zero, or whatever the appropriately number is for the patch version, so that Node.js doesn't throw a compilation error.

• CHANGELOG.md file needs to be updated.

• Any related documentation (How-to or API doc) needs to be manually updated for now. In v3.0 of the repo I hope to enable the ability to create the docs automatically from code comments.

• Write unit tests or create new unit test files to validate any new functionality. On a related note, currently the unit tests are written in Jasmine and they run separately from the build process. They all live under /offline-editor-js/tests/ and are manually (I know...old school) run in a browser window.

• To do the build, the grunt build command runs a process that does all the heavy lifting for you. It runs jshint, jslint, and concatenates the src files in the correct order. Next, it creates the min files and then creates (or overwites if the files already exist) all the final source and minified files under /dist.

  This sample repo demonstrates the concepts behind the build pattern that is used to create the /dist files.

• For major and minor releases (e.g. v2.0 and v2.1, respectively), merge gh-pages on the local fork, push to the remote fork in your personal github repo, and then create a PR to the official https://github.com/Esri/offline-editor-js/gh-pages branch. I have a TO-DO note to automate this step in the future.

• Create a new release package for major and minor releases. Patch releases that only include minor, non-critical path documentation updates don't need an associated release.

• Whew, that should do it! It sounds like a lot but it goes quickly for minor updates.

---

Breakdown of git/github steps (my notes for others that wish to create pull requests).

• Create a new branch in your local git and make updates to the new branch, not the master branch. One suggestion for easy management: use the version number like “v2.12” etc. That just makes it easier for you to track later on your local git.
• My own personal preference is the very last commit that I make it to move all the final /dist files, CHANGELOG and package.json files and name that one, single commit under the version number of the release. That irrevocably stamps the commit in a way that is universally recognizable by anyone.
• Do a pull and merge on the upstream (github.com/esri) branch. That way you are in-sync with the latest golden copy of the public master branch. If you accidentally skip this step you may be guaranteeing yourself of having to work thru a merge conflict on your local machine. It's always just a good idea to stay in sync with master.
• Push your new branch to your public github fork.
• Now you can go to your personal page on github and review the changes/diffs. It’s a great place to see if the CHANGELOG looks correct and to review, via the browser, any potential documentation changes. Sometimes .md files get garbaged up and this lets you view them before making the final pull request to esri/master.
• Open a pull request on esri/master from your github fork page. Call it “vX.X.x” and dump your CHANGELOG text into the content body. I always just give the “review” tab a quick glance to make sure the text is readable. Github will tell you if there are any merge conflicts. If there aren’t then initiate the pull.
• I’ll review it. If it looks good then I pull it across and the request is completed. You’ll get an email notification.
• Once that’s done, on your local git checkout master and do “git pull upstream master”. This steps completes the loop and will ensure that the local git, your remote fork and esri/master are all in sync. Muy importante!
• On your local git checkout gh-pages and merge gh-pages into the last commit you just did. I use the application called Source Tree do this visually. Just my preference, since I can see all the changes in one spot in a way that’s very easy to read.
• Now push your local gh-pages commit to your personal github gh-pages. Again, here I use SourceTree. Go to your personal github account. Use the pulldown to switch to the gh-pages branch and from there create a pull request. Very the changes. Call it simply “Update gh-pages” and there’s no need to fill out any text description, IMHO. If there aren’t any merge conflicts reported by github, like before go ahead and initiate the pull. I’ll review it. If it looks good then I pull it across and the request is completed. You’ll get an email notification.
• Once that’s done, on your local git checkout gh-pages and do “git pull upstream gh-pages”. This completes the loop and will ensure that the local git, your remote fork and esri/gh-pages are all in sync. That should be it!!!