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.
We use the GitHub issue tracker to track bugs and features in development. If you notice any bugs while using Streetmix, please let us know by opening a new issue.
Note: before suggesting a new feature or reporting a bug, 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. Shoot us an email or open an issue.
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.
brew install mongodb
You'll also need to set up the MongoDB data directory. The easiest set up would be (you may need sudo):
mkdir -p /data/db
chmod 777 /data/db
-
Clone this remote repository to a folder on your computer.
git clone https://github.com/codeforamerica/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/codeforamerica/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
-
Set up the MongoDB environment. Follow the instructions under “Set up the MongoDB environment” from the MongoDB website.
- 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? |
|---|---|---|
SENDGRID_USERNAME |
Your SendGrid username | Yes |
SENDGRID_PASSWORD |
Your SendGrid password | Yes |
TWITTER_OAUTH_CONSUMER_KEY |
Twitter OAuth consumer key | Yes |
TWITTER_OAUTH_CONSUMER_SECRET |
Twitter OAuth consumer secret | Yes |
EMAIL_FEEDBACK_RECIPIENT |
Your e-mail address | No |
NO_INTERNET_MODE |
Boolean. Set to true to run a local "demo" without external Internet access |
No |
A sample .env file will look like this:
[email protected]
SENDGRID_PASSWORD=p@$$w0rD
TWITTER_OAUTH_CONSUMER_KEY=twitteroauthconsumerkey
TWITTER_OAUTH_CONSUMER_SECRET=twitteroauthsecrettoken
[email protected]
NO_INTERNET_MODE=true
Note: If NO_INTERNET_MODE is true, you do not need the Sendgrid or Twitter authentication keys, as those will be disabled due to lack of Internet.
-
Start the web server. (This also automatically starts MongoDB in the background.)
cd streetmix npm start
-
Load the application in your web browser.
-
Install test dependencies (only required once, or after major updates to depedencies)
grunt test:local:setup
-
Run browser tests locally
grunt test:local