In the spirit of open source, everyone is encouraged to help improve this project! Please keep these guidelines in mind in order to make your contributions as useful as possible.
There are many ways to contribute to the project, not just through code. For instance:
- Design
- Illustrations
- Writing
- Community management
- Translation and localization
- and of course, financially.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
We use the GitHub issue tracker to track bugs and features in development. We also have a Discord server for feedback and discussion.
If you notice any bugs while using Streetmix, let us know by opening a new issue. Please check to make sure it hasn't already been reported. If there is already an existing issue, feel free to add a comment or indicate support by voting it up.
When submitting a new issue, please include the following information:
- What web browser you're using (i.e. MS Internet Explorer, Google Chrome, Firefox), what version (i.e. 9.0, 27), and what operating system you're using (i.e. Mac OS X 10.8, Windows 7, Android 4.1).
- If you are running a local copy, include details about your enviroment that's necessary to reproduce the bug, such as your node version, npm version, and operating system.
- What you expected to happen when you encountered the bug.
- What actually happened.
- Steps we can follow to reproduce the bug.
- Any other information you think might be at all helpful.
If you have any ideas for new features or functionality for Streetmix, we'd love to hear about them! Unfortunately, we can't promise to build everything, but we are receptive to all thoughts you have on how Streetmix could be more useful. You can open an issue on GitHub or talk to us in Discord.
Again, please make sure it hasn't already been posted. Posts or issues that are similar ones may be closed.
If you have the capacity to write code, and wish to contribute to Streetmix, we'd love your help!
A request: before you write any new feature or code, please open an issue, or comment on the issue you'd like to work on. That way the maintainers of the project can guide your work from the outset, making it more likely that we'll be able to accept your work when it's ready.
In general, you can help by:
- Writing or editing documentation
- Writing code (no patch is too small: fix typos, add comments, clean up inconsistent whitespace)
- Refactoring code
- Closing issues
- Reviewing patches
Once your code is ready, please push your work to a feature branch on your fork of the Streetmix repo, and submit a pull request to us.
- Fork the project.
- Create a topic branch.
- Implement your feature or bug fix.
- Commit and push your changes.
- Submit a pull request.
Individuals making significant and valuable contributions are made Collaborators and given commit-access to the project.
Unfortunately, we are not accepting illustration contributions at this time. If you have feedback on our illustrations, or if you think we should consider adding new elements, please follow the instructions for feature requests/feedback above.
These installation instructions assume that you have already installed the Homebrew package manager.
-
Download and install Node.js.
brew install nodejs
-
Download, install and start MongoDB v3.4.
brew install mongodb@3.4
-
Set up the MongoDB data directory. The easiest set up is this (you may need
sudo):mkdir -p /data/db chmod 777 /data/db
-
Add MongoDB binaries to the PATH environment variable. The most common way this can be done by editing
~/.bash_profile. Using a text editor, open that file and add this line at the bottom of it:export PATH="/usr/local/opt/mongodb@3.4/bin:$PATH" -
Clone this remote repository to a folder on your computer.
git clone https://github.com/streetmix/streetmix.git
-
Install project dependencies.
cd streetmix npm install
Streetmix was not developed on a Windows platform, and testing is limited. We've been able to successfully stand up a local installation on 64-bit Windows 7-based Dell laptops for an event without Internet access. These instructions below will assume that the user has basic familiarity with Git, GitHub, and the Windows Terminal command line interface, and has administrative permissions to install software on the machine.
You may skip each of these steps if a fairly recent stable version is already present on the system.
- Install Git.
- Install node.js. The site should detect your system and provide you with the correct installer, but you may specify the package at http://nodejs.org/download/ (e.g. Windows 64-bit installer).
- Install MongoDB. Select the appropriate Windows installer package from their downloads page.
- Install a modern browser. Streetmix has been tested in Chrome (preferred), Firefox, Safari, and Internet Explorer 11. (Previous versions of Internet Explorer will not work.)
-
In the command line terminal, clone a copy of the Streetmix repository to your local machine:
git clone https://github.com/streetmix/streetmix.git
You may additionally specify the name of the directory to install to, if you wish.
-
Go into the project’s root directory and install all Node libraries.
cd streetmix npm install -
Go into
package.jsonand remove"prestart": "npm run mongo:start"and"mongo:start": "mongod --fork --logpath /dev/null" -
Set up the MongoDB environment. Follow the instructions under “Set up the MongoDB environment” from the MongoDB website.
-
Add MongoDB binaries to your system path. Open the Start Menu and type in "environment variables", and select Edit the system environment variables. You should see the Advanced tab of System Properties. Click "Environment Variables..." at the lower right corner of the panel. In the user variables, select or create a variable called "Path", then edit it and add a new entry containing
C:\Program Files\MongoDB\Server\3.6\bin(or the path you installed MongoDB to). Click OK until you return to the System Properties window, click Apply then click OK to exit. -
Run
mongod.exeandmongo.exe
- Setup environment variables. You can either set these in your
.bash_profile(or equivalent, on Mac OSX or *nix-based systems) or place them in a file named.envin the project root directory (great for development environments or Windows environments).
| Variable name | Description | Required? |
|---|---|---|
AUTH0_CLIENT_ID |
Auth0 client ID | Yes |
AUTH0_CLIENT_SECRET |
Auth0 client secret | Yes |
PELIAS_API_KEY |
Geocoding (Pelias) API key | No |
IPSTACK_API_KEY |
Geolocation (IPStack) API key | No |
TRANSIFEX_API_TOKEN |
Your Transifex API token | No |
TWITTER_OAUTH_CONSUMER_KEY |
Twitter OAuth consumer key | (deprecated) |
TWITTER_OAUTH_CONSUMER_SECRET |
Twitter OAuth consumer secret | (deprecated) |
A sample .env file will look like this:
AUTH0_CLIENT_ID=1234567890
AUTH0_CLIENT_SECRET=abcdefghij
PELIAS_API_KEY=a2c4e6g8i
Set your NODE_ENV environment variable to demo.
Note: When you are running Streetmix on a platform without Internet access, you do not need to provide authentication keys for third-party services like Twitter.
-
Start the web server. (This also automatically starts MongoDB in the background.) In the Streetmix project directory, run:
npm start
-
Load the application in your web browser by navigating to
http://localhost:8000or by running in your terminal:open http://127.0.0.1:8000
-
By default, local tests are unit tests, with CSS and JavaScript linting.
npm test -
You can run a full browser integration test with this command. By default, we run tests similar to this in our continuous integration infrastructure on commits and pull requests to GitHub, so it is not required to run this locally.
npm test:full