Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update and revise contributing guide #158

Merged
merged 5 commits into from
Feb 12, 2022
Merged

Update and revise contributing guide #158

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
398cd9b
docs: move config file section to after installing dependencies
zekefarwell Feb 12, 2022
df6194f
docs: revise better explain new requirements and platform specific n…
zekefarwell Feb 12, 2022
535f3bf
docs: add note about sudo
zekefarwell Feb 12, 2022
adfc282
Update CONTRIBUTE.md
ZeLonewolf Feb 12, 2022
abe4a00
Update CONTRIBUTE.md
ZeLonewolf Feb 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 82 additions & 62 deletions style/CONTRIBUTE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,113 +7,131 @@ The repository is organized as follows:
- **layer/** - Individual style layers, organized by subject area
- **icons/** - SVG icons, which get converted into PNG stylesheets
- **constants/** - Style elements that are frequently re-used
- **js/** - Dynamic javascript code for highway shields and stylesheet building
- **config.js** - Configuration settings (MapTiler API key, OpenMapTiles URL, etc)
- **americana.js** - OpenMapTiles loader with layer ordering
- **index.html** - Demonstration map HTML page

## Config File
## Install Node.js

Environment specific settings go in the untracked file `config.js`. Copy the template
`config.default.js` and rename it `config.js`. The variables in this file can then
be changed without the risk of accidentally comitting to the main repo.
Any [currently supported version of Node.js][31] should work. The current LTS
release is recommended. Installation options:

You can create a new copy of the config file by running `npm run config`
- Download and run the installer from [nodejs.org][52]
- Install via package manager (See [platform specific notes](#platform-specific-notes) below)
- [Use NVM][30] to manage multiple different Node.js versions

### MapTiler API Key
## Update NPM

By default this project is set up to use vector tiles provided by MapTiler.
For this to work, you must create an account and obtain a free key from
[MapTiler Cloud][20]. This key should be pasted into the `MAPTILER_KEY` variable of
the `config.js` file.
NPM is included with the Node.js install, but as **NPM version 8.3** or newer is required
for this project, you may need to update it. To [update NPM to the latest version][32],
run either of these commands:

### Custom OpenMapTiles URL
```
npm update -g npm
```

For testing upcoming features of the [OpenMapTiles schema][21] or for fresher data than
MapTiler Cloud provides, a custom vector tile url can be set in the `OPENMAPTILES_URL`
variable of the `config.js` file. However, this requires setting up a custom OpenMapTiles
server which is beyond the scope of this guide.
```
npm install -g npm@latest
```

[20]: https://cloud.maptiler.com/maps/
[21]: https://openmaptiles.org/schema/
It may be necessary to prefix these with `sudo` depending where NPM is installed on your system.

## Install Pre-requisites
[30]: https://heynode.com/tutorial/install-nodejs-locally-nvm
[31]: https://nodejs.org/en/about/releases/
[32]: https://docs.npmjs.com/try-the-latest-stable-version-of-npm

These development tools are required and must be installed manually on your system:
## Platform Specific Notes

- **NodeJS Node.js 17.3** or newer with **NPM 8.3.0** or newer
### MacOS

See platform specific installation instructions below. Users of other platforms are
encouraged to contribute additional OS-specific instuctions. These instructions install
NodeJS directly, but if you need multiple versions another option is to [use NVM][30].
MacOS doesn't include a default package manager, but Node.js and NPM can be installed via
[Homebrew][50] or [MacPorts][51]:

[30]: https://heynode.com/tutorial/install-nodejs-locally-nvm
- Homebrew - `brew install node`
- MacPorts - `sudo port install npm8`

### Ubuntu Linux
#### Apple Silicon/ARM Macs

The NodeJS & NPM packages available from the default Ubuntu repos are generally out of
date. To get newer versions you'll need to add the [NodeSource][40] repo.
Running the project natively on an Apple Silicon Mac is not currently possible due to
[dependency issues][62]. However, it is possible to work around this by [running the
project through Rosetta][63].

- **Add NodeSource repo** - `curl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash -`
- **Install NodeJS & NPM** - `sudo apt install nodejs`
### Windows

[40]: https://github.com/nodesource/distributions/blob/master/README.md
Running the project natively on Windows is not currently possible due to [dependency issues][61].
Instead running on [Ubuntu](#ubuntu-linux) via [Windows Subsystem for Linux][60] is recommended.

### MacOS
### Ubuntu Linux

Since MacOS doesn't include a package manager you'll need [Homebrew][50] or [MacPorts][51].
The Node.js packages in the default Ubuntu repos are generally out of date. Instead, it is
recommended to use the [NodeSource repositories][40] for installing Node.js via APT. You can [choose
a specific version][41], or install the current LTS release:

- **Install NodeJS & NPM**
- Download and run the installer from [nodejs.org][52]
- _Or_ via Homebrew - `brew install node`
- _Or_ via MacPorts - `sudo port install npm7`
```
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install nodejs
```

[40]: https://github.com/nodesource/distributions/blob/master/README.md
[41]: https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions
[50]: https://brew.sh/
[51]: https://www.macports.org/
[52]: https://nodejs.org

### Windows

Running Ubuntu via [Windows Subsystem for Linux][60] is recommended. Follow the
instructions for [Ubuntu Linux](#ubuntu-linux) above.

Running the project natively on Windows may also be possible but instructions have not
been written.

[60]: https://docs.microsoft.com/en-us/windows/wsl/install-win10
[61]: https://github.com/ZeLonewolf/openstreetmap-americana/issues/132#issuecomment-1036976993
[62]: https://github.com/ZeLonewolf/openstreetmap-americana/issues/132
[63]: https://github.com/ZeLonewolf/openstreetmap-americana/issues/132#issuecomment-1027274543

## Install Project Level NPM Dependencies

NPM dependencies are tracked in the `package.json` file and are installed with one command:
All other dependencies are installed via NPM. Dependencies are listed in the `package.json`,
and `package-lock.json` files. Run this command to install them in the project directory:

`npm install --include=dev`

This step is the same on all platforms. It installs the following packages locally to
the project:

- **[browser-sync][70]** - to run a local web server with live reloading
- **[spritezero][71]** - to combine icons into a sprite sheet
- **[prettier][72]** - to keep our code style consistent

[70]: https://browsersync.io/
[71]: https://github.com/mapbox/spritezero
[72]: https://prettier.io/
`npm install`

### NPM Troubleshooting

If you run into permissions errors with NPM, setting the user with this command may
help: `npm -g config set user $USER`. Issues like this this can usually be avoided by
[not running `npm` with `root` or `sudo`][80]. Another good troubleshooting step is
simply deleting the `node_modules` folder and re-running `npm install`.
simply deleting the `node_modules` folder (contains all the installed dependencies)
and re-running `npm install`.

[80]: https://medium.com/@ExplosionPills/dont-use-sudo-with-npm-still-66e609f5f92

## Config File

Environment specific settings go in the untracked file `config.js`. Copy the template
`config.default.js` and rename it `config.js`. The variables in this file can then
be changed without the risk of accidentally comitting to the main repo.

You can create a new copy of the config file by running `npm run config`

### MapTiler API Key

This project can use vector tiles provided by MapTiler.
For this to work, you must create an account and obtain a free key from
[MapTiler Cloud][20]. This key should be pasted into the `MAPTILER_KEY` variable of
the `config.js` file.

### Custom OpenMapTiles URL

For testing upcoming features of the [OpenMapTiles schema][21] or for fresher data than
MapTiler Cloud provides, a custom vector tile url can be set in the `OPENMAPTILES_URL`
variable of the `config.js` file. However, this requires setting up a custom OpenMapTiles
server which is beyond the scope of this guide.

[20]: https://cloud.maptiler.com/maps/
[21]: https://openmaptiles.org/schema/

## Running the Americana style

### In development...

```
cd style/
npm i --include=dev
npm install
npm start
```

Expand All @@ -129,7 +147,7 @@ restart the web server.

```
cd style/
npm i --include=dev
npm install
npm run build
```

Expand All @@ -140,4 +158,6 @@ for distribution.
## Before submitting a PR

Please prettify all files prior to submission. Run `npm run code_format` to format all
code files with js-prettifier.
code files with [prettier][90].

[90]: https://prettier.io/