lieuzhenghong/districtr

A free, open-source web app for drawing districting plans.

Districtr

Districtr is the open-source web app that empowers all people to draw districting plans.

Project values

• User experience. Participating in the redistricting process should be easy and enjoyable.
• Openness and transparency. The entire project is open-source, with permissive licenses. All of the data used in the app is freely available and well-documented. We explicitly declare where we get our data, how we've processed it, and what we think of its quality.
• Responsiveness to the community. Different places have different values and priorities when it comes to drawing districts. We aim to highlight the specific concerns of the community in each place that we include in the app.

See also the Districtr Guiding Principles prepared by participants in MGGG's 2019 Voting Rights Data Institute.

Contributing

If you're interested in contributing, thank you! Send an email to [email protected] and we'll find a way that you can get involved.

Development

Here's how to get started.

1. Install GitHub for Desktop (or just plain git), Node.js, and a helpful text editor. We recommend VS Code.
2. Clone the repository using GitHub for Desktop, or by running git clone https://github.com/districtr/districtr from the command line.
3. Install the dependencies by running npm install.
4. To start the development server and make sure everything's set up, first run npm run develop. If you go to http://localhost:3000, you should see Districtr running. The development server will recompile the app's assets, JavaScript, HTML, and CSS as you edit the source files.

Districtr is built on Mapbox GL JS and lit-html. We also use Sass for authoring CSS.

We use Prettier for formatting JS source code and ESLint for linting (encouraging good habits and consistent coding style).

Naming conventions

JavaScript

We use PascalCase for classes and components (e.g. UIStateStore or DataTable). By "component", we mean any function that returns a lit-html TemplateResult, or a class with a .render() method that does the same. We use camelCase for everything else (e.g. variables and functions).

For file naming, we use PascalCase for files that export one main class or component (e.g. Layer.js or LayerTab.js). We use kebab-case for other JavaScript modules (e.g. color-rules.js or routes.js).

CSS

We try to use BEM (block-element-modifier) naming conventions for CSS classes.

Testing

To run the unit test suite, run npm run test. We use the Mocha test framework and the Chai assertion library. We need to write more unit tests!

Reporting bugs and other issues

One of the best ways to contribute to Districtr (or any open source project) is to report any bugs, problems, or points of confusion that you find. You can file an issue in this GitHub repository.