Skip to content

Latest commit

 

History

History
63 lines (48 loc) · 5.45 KB

RELEASE_DOCUMENTATION.md

File metadata and controls

63 lines (48 loc) · 5.45 KB
Raw

Branch Web SDK Build and Release Documentation

Last Updated: Sep. 24th, 2015

The entire process for releasing new versions of the Branch SDK, and generating accompanying documentation, is entirely automated.

Features of Build and Release Automation

  • Makefile

    • Building and minification with Google Closure Compiler
    • gzip of minified JavaScript
    • Embedding of Branch snippet on the Web testbed
    • Embedding of Branch snippet on the integration Mocha.js test page
    • Documentation generation from JSDoc style inline comments from src/3_branch.js
    • Concatenation of a summary README that includes an introduction, most recent Web snippet, and overview of Web Smart Banner
    • Concatenation of full documentation for Web of an introduction, an automatically generated table of contents, and JSDoc generated function descriptions and spec.

  • Release.sh

    • Version number management in 0_config.js, package.json, CHANGELOG.md, bower.json, Git commit and tag
    • Build a release build with the Makefile
    • Upload both the minified and gzipped Web SDK, and the example web testbed to S3
    • Publish to npm
    • Reset everything: Changelog unreleased version at top, clean and remake, then commit
    • Reminder to update the Branch integration guide - soon to be automated

Documentation

Important Note: The majority of the documentation markdown files for the Web SDK are generated - meaning that any changes made directly to them will not survive running make, and will be overwritten. All generated filed are concated from components of the documentation in the docs folder, or generated from comments in src/3_branch.js.

Files that are generated

  • README.md
  • WEB_GUIDE.md

Files that can be edited directly

  • CHANGELOG.md - Note: The changelog should only be edited directly under the unreleased version: ## [VERSION] - unreleased
  • RELEASE_DOCUMENTATION.md (this file)
  • SMART_BANNER_GUIDE.md - An in-depth guide explaining every feature of the smart app sharing banner

Editing the main README (README.md)

The markdown files concatenated together to make the main README, can be seen in the README.md target of the Makefile. In summary, the files consist of:

File Edit Directly? Content
docs/0_notice.md ✗ A notice placed at the top of every generated document, that any edits made to the following file will be overwritten.
docs/readme/1_main.md ✔ The content of the README file, along with a placeholder for the Branch init code to be put. This is done with a perl string substitution regex. Any edits to the content of the README file should be made here.
docs/4_footer.md ✗ A generic footer placed at the end of all documentationt that includes an email where bugs and feature requests can be dropped.

Editing The Full Web SDK Documentation (WEB_GUIDE.md)

The markdown files concatenated together to make the Full Web SDK documentation, can be seen in the WEB_GUIDE.md target of the Makefile. The introduction (docs/web/1_intro.md), is the only markdown file that should be edited directly. The Tabe of Contents (docs/web/2_table_of_contents.md), and the bulk of the readme (docs/web/3_branch_web.md), are both generated from the source code for the main Branch class src/3_branch.js.

File Edit Directly? Content
docs/0_notice.md ✗ A notice placed at the top of every generated document, that any edits made to this file will be overwritten.
docs/web/1_intro.md ✔ An introduction to the Web SDK, showing current Browser compatibility, basic installation of the Branch Web SDK, and other high level items that are important for basic implementations of the Web SDK. An up-to-date embed code is automatically placed here by the Makefile.
docs/web/2_table_of_contents.md ✗ The Table of Contents of every function of the Branch Web SDK. This file is generated by passing src/3_branch.js into a simple perl program: build_utils/toc_generator.pl. Instructions for use of the Table of Contents generator can be found in the comments at the top of it, and examples can be seen of the exitisting Table of Content items in src/3_branch.js
docs/web/3_branch_web.md ✗ The full specification of every function of the Web SDK. This entire file is generated using JSDoc/JSDox from the comments found in src/3_branch.js. Whenever a new function is added to the Branch class, or a function is edited, be sure to make the appropriate documentation changes to the comments above the function.
docs/4_footer.md ✗ A generic footer placed at the end of all documentationt that includes an email where bugs and feature requests can be dropped.

Releasing the Web SDK

The entire release process has been encapsulated into a single shell script: release.sh. The release script has a few dependencies you'll need to make sure you have installed: AWS CLI, make, and you'll need environment variables to upload the SDK and Web testbed to S3. For convenience, I've placed mine in a simple shell script that I have added to .gitignore: aws_access_keys.sh

The release shell script is a simple wizard. Once your S3 environment variables are set, and you have been added to the Branch npmjs.org account, simple run :./release.sh and follow the steps.