Notes for developers.
Mapbox Studio Classic relies on its dependencies for key parts of its functionality. When reporting an issue or looking into fixing/improving functionality Mapbox Studio Classic know that a dependent module may be the right place to focus your efforts.
- carto parses and interprets CartoCSS
- mapnik and node-mapnik provide core tile rendering functionality
- mapnik-omnivore does the dirty work when autodetecting projection and other metadata of datasources
The packaged desktop app version of Mapbox Studio Classic uses atom shell as an app wrapper. To use atom shell to test studio in development:
-
Download the latest release of atom shell from https://github.com/atom/atom-shell/releases
-
Unzip it and run the
atom
binary pointing at your mapbox-studio repo:./atom /path/to/your/mapbox-studio
Mapbox Studio Classic targets the latest stable release of Node.js. When you install Mapbox Studio Classic the target version of Node.js is vendorized locally at ./vendor/node
. The version is controlled via the NODE_VERSION
environment variable.
- For packaged builds this variable is set in the
.travis.yml
config - For local source installs the default node version is found in
scripts/vendor-node.sh
but it can be overriden by settingNODE_VERSION
in your environment before runningnpm install
.
For Linux and Mac the version must be packaged ahead of time with install-node.
For Windows custom builds need to be done and available at https://github.com/mapbox/node-cpp11. This means that:
- The node installs from https://nodejs.org/download are not supported for Windows.
- To release a new Mapbox Studio Classic version for Windows against a new Node.js version Windows binaries need to first be built via the toolchain at https://github.com/mapbox/node-cpp11.
Mapbox Studio Classic has an application log and a shell log for error reporting and application messages for the Mapbox Studio Classic server and Atom shell, respectively. On Linux and OSX, app.log
and shell.log
are located in ~/.mapbox-studio/
. On Windows, app.log
and shell.log
can be found in C:\Users\<YOUR-USER-NAME>\.mapbox-studio
.
On OSX, the logs can also be accessed to through the Help dropdown on the top menu bar.
Note: some tests are expected to fail without proper AWS credentials. Team Mapbox should use mapbox auth
before running the tests.
The majority of tests can be run like:
npm test
These test that the UI functions as we expect:
./test/test-client.js
They run slowly, so if you are debugging failing tests you may want to run just the tests that are failing. You can run just a single test by passing the test name like:
./test/test-client.js source
See the entire list of tests here
These test that the web pages that make up the documentation build okay:
./jekyll-test.sh
Use PRs for everything but trivial changes and typos. Goals to strive for:
- Is the change sustainable,
- Is it tested (including error/corner cases),
- Is it documented (CHANGELOG.md, docs/)
Docs live in the /docs
dir and are .md
files that are built by jekyll on the Mapbox Studio Classic website. Rules!
- Keep docs consolidated and sustainable. Let's add docs sparingly and focus on improving what we have.
- Do not commit doc images (screenshots, diagrams, etc.) to the mapbox-studio repo. Host them externally, either on github's issue image hosting or elsewhere.
- Could the need to document be eliminated by improving the software (UI/UX/code)?
To running website locally:
gem install jekyll
jekyll serve
- Make sure the tests are passing, on both travis and appveyor
- Run
npm ls
and make sure it presents no errors - Run
npm dedupe
and see if any of theunavoidable conflicts
are actually avoidable, say by bumping thenode-pre-gyp
version kept inpackage.json
Tagging flow is like this:
# Update version number in package.json using vim or your favorite editor
# Commit package.json change and tag it.
git commit package.json -m "v0.0.1"
git tag v0.0.1
# Confirm the tag.
git tag -n
# Push all the things to github
git push origin mb-pages
git push --tags
Then package using the tag name in the steps below.
Travis bundles Mapbox Studio Classic with the atom-shell wrapper and uploads packages to S3 for hosting. There are two OSs in the travis matrix:
- linux: builds linux, win32 platforms
- osx: builds darwin (because of osx-only code signing tools)
To package:
-
Push a commit with
[publish GITSHA]
as the message.GITSHA
should be a commit hash, branch name, or tag that can be used withgit checkout
. Note: the packaging process itself will use the code in the repo as of GITSHA -- in other words, your GITSHA must be able to package itself. -
Watch travis for a for success. When complete downloads will be available at https://mapbox.s3.amazonaws.com/mapbox-studio/index.html in the format of:
https://mapbox.s3.amazonaws.com/mapbox-studio/mapbox-studio-classic-linux-x64-{GITSHA}.zip https://mapbox.s3.amazonaws.com/mapbox-studio/mapbox-studio-classic-darwin-x64-{GITSHA}.zip https://mapbox.s3.amazonaws.com/mapbox-studio/mapbox-studio-classic-win32-x64-{GITSHA}.exe
-
If a tagged release, update _config.yml, _config.mb-pages.yml. Update the
release
key in_config.yml, _config.mb-pages.yml
to be the name of the tag.