Home

Welcome to the Tangram Play wiki!

Release / deployment plan

• The production (release) branch is master. Code here is tested and documented, and should be considered stable. It will auto-deploy to our staging server for testing, and it will deploy to production only when a release is tagged. This means the production deployment can lag behind the master branch of the code.
• Make changes in feature branches, and make a pull request when ready. Keep pull requests small to make them easier to review. The merging policy enforced on GitHub is to that the feature branch should be up-to-date with master, so that the PR requester is responsible for cleaning up merge conflicts.
• Request a review from another maintainer. Pull requests will require at least one approval to merge. Project administrators can override this.
• The code on master will be deployed to production when a commit is tagged in the format of release-vX.X.X where X.X.X is a semver-compatible version number. Project maintainers can mark a release at their discretion. Production code should be deployed early in the week and early enough in the day that bugs and problems can be addressed during the workday. “Patch day” does not have to be rigid (especially for important bug fixes) but it helps to not have surprises.
• A short, incomplete checklist of items before cutting a release:
  • Run yarn upgrade locally to sync yarn.lock with updates to package.json (can be updated via Greenkeeper.io)
  • Smoke check the updated build on staging
  • Update the version number at package.json
  • Update the internal version number at version.json
  • Update the public-facing changelog (see below)
• Process for updating the release and deploying it:
  • Make sure all changes you want in the release have been committed, including version number updates.
  • Tag the release with git tag release-vX.X.X
  • Push tags with git push origin --tags
  • Watch progress on Circle.CI!

There is a staging server

A staging server exists at https://dev.mapzen.com/ (Mapzen staff login required for platform features). This is necessary to test features that are integrated with the Mapzen platform, like user login, or saving scenes. Changes to the master branch will auto deploy to dev for testing, and it does not need to wait for a release tag.

There is a secondary staging branch which also auto-deploys to dev. This branch can be force-pushed to (unlike master) and can contain experimental work-in-progress code that needs to be tested in dev, but is not ready or stable for master. Note that changes in staging should not flow to master. Instead, keep your commits in its own branch, and merge to staging for testing and make a pull request to master when ready.

This means dev may contain the contents of either master or staging branch depending on what was last committed to. This is not ideal, but it helps us keep the number of staging environments to a minimum amount.

Public facing changelog

A public-facing changelog of bug fixes, improvements and/or new features will be published in-app. This changelog is not a raw list of commit messages. It should be written in a friendly, accessible manner, in order to communicate to users what features or bug fixes have occurred since the last update.

This means that behind-the-scenes architecture improvements (like “We refactored X component”) is not important for the public changelog, unless it can be written to describe how it improves the public-facing experience (for example, “We fixed a bug that can sometimes cause Y”, “doing Z is faster now”). We are not currently maintaining a changelog for internal use (besides the commit history) but this can be revisited later.

Since the changelog will display on every new release, it is better to say something rather than nothing.