Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/codeforboston/police-data-trust
A national archive of police data collected by journalists, lawyers, and activists around the country.
https://github.com/codeforboston/police-data-trust
accountability open-government police-misconduct transparency
Last synced: 11 days ago
JSON representation
A national archive of police data collected by journalists, lawyers, and activists around the country.
- Host: GitHub
- URL: https://github.com/codeforboston/police-data-trust
- Owner: codeforboston
- License: mit
- Created: 2021-02-26T12:35:31.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-30T02:51:27.000Z (17 days ago)
- Last Synced: 2024-10-30T05:12:42.531Z (17 days ago)
- Topics: accountability, open-government, police-misconduct, transparency
- Language: Python
- Homepage: https://www.nationalpolicedata.org
- Size: 107 MB
- Stars: 46
- Watchers: 17
- Forks: 80
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# police-data-trust
To get started:
1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) a copy of the main repo to your GitHub account.
2. Clone your fork: `git clone [email protected]:YOUR_GITHUB_NAME/police-data-trust.git`
3. Add the main repo to your remotes
```
cd police-data-trust
git remote add upstream https://github.com/codeforboston/police-data-trust.git
git fetch upstream
```
Now, whenever new code is merged you can pull in changes to your local repository:
```
git checkout main
git pull upstream main
```
## Installation (Full Application)
This method uses Docker to run the complete application stack.
1. Make sure that [Docker](https://www.docker.com) is installed on your machine.
2. Create a `.env` file by running `cp .env.template .env` in the root of your local project folder, and add your preferred PostgreSQL username and password:
> **Note**
> When running locally, you may need to update one of the ports in the `.env` file if it conflicts with another application on your machine.
3. Build and run the project.
```
docker-compose build && docker-compose up -d && docker-compose logs -f
```
## Installation (Frontend Only)
This method runs the frontend natively on your computer and does not require a running backend, which can be convenient.
1. Make sure that you have `node 16+` and either `npm 7+` or `yarn` installed.
2. Follow the [install instructions](./frontend/README.md) in the `frontend` directory.
## Testing with Docker
All code must pass the unit tests and style checks before it can be merged into the main branch. You can run the tests locally by opening up a comand line interface to a docker container while it's running the application:
```
docker exec -it "police-data-trust-api-1" /bin/bash
```
You'll need to replace `police-data-trust-api-1` with the name of the container you'd like tro connect to. You can see the names of all currently running containers by running `docker container ls`
```bash
docker container ls
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c0cf******** police-data-trust-api "/bin/sh -c '/wait &…" About a minute ago Up About a minute 0.0.0.0:5001->5001/tcp police-data-trust-api-1
5e6f******** postgres:16 "docker-entrypoint.s…" 3 days ago Up About a minute 0.0.0.0:5432->5432/tcp police-data-trust-db-1
dacd******** police-data-trust-web "docker-entrypoint.s…" 3 days ago Up About a minute 0.0.0.0:3000->3000/tcp police-data-trust-web-1
```
### Backend Tests
The current backend tests can be found in the GitHub Actions workflow file [python-tests.yml](https://github.com/codeforboston/police-data-trust/blob/0488d03c2ecc01ba774cf512b1ed2f476441948b/.github/workflows/python-tests.yml)
To run the tests locally, first start the application with docker compose. Then open up a command line interface to the running container:
```
docker exec -it "police-data-trust-api-1" /bin/bash
```
Then run the tests:
```
flake8 backend/
python -m pytest
```
For more information on running the tests, see the [backend tests README](./backend/tests/README.md)
### Front End Tests
The current frontend tests can be found in the GitHub Actions workflow file [frontend-checks.yml](https://github.com/codeforboston/police-data-trust/blob/0488d03c2ecc01ba774cf512b1ed2f476441948b/.github/workflows/frontend-checks.yml)
To run the tests locally, first start the application with docker compose. Then open up a command line interface to the running container:
```
docker exec -it "police-data-trust-web-1" /bin/bash
```
Then run the tests:
```
npm run lint
npm run check-formatting
npm run test
npm run check-types
```
# Documentation
[Docs](https://codeforboston.github.io/police-data-trust)
# Code Standards
## Typescript Style Guide
This style guide is intended to act as a quick reference for the most common scenarios
### Custom Types
For this codebase, we are using [interfaces](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#interfaces) instead of [type aliases](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-aliases).
### Utilizing Types
- We are aiming for a loose standard of explicitly typing as little as possible (relying on type inference or third-party library typing files to do the work whenever convenient), but as much as necessary (function params/args are a good example of what the compiler is bad at inferring). Erring on the side of 'stricter than absolutely necessary' definitely works for us!
- The [`any`](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any) type should never be utilized here. Prefer [union types](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types) in the case of values that are initially `null` (such as values that come from API calls), or [`unknown`](https://www.typescriptlang.org/docs/handbook/2/functions.html#unknown) in case of a type being truly impossible to discern ahead of time.
- When typing primitive values declared with `const`, explicitly typing them will be necessary to prevent their type from being implied as the literal value of said primitive, rather than it's corresponding data type.
## Functions
- Always use explicit typing in the case of function params and return types.
- If function parameters don't get modified by the function, strongly consider making them `readonly` to prevent mutation and have clearer code.
## React
- Prefer the `.tsx` file extension when JSX is involved, and `.ts` when it isn't.
### Props
- Refer to the [React/TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/basic_type_example) for examples of common propTypes.
- In the case of components that accept other React components as props, prefer typing those as `React.ReactNode`.
### Hooks
- Prefer type inference for `useState` for simple cases. If the hook initializes with a nullish value, strongly consider a union type.
- Since `useEffect` and `useLayoutEffect` don't return values, typing them is not necessary.
- When typing `useRef`, refer to the React/TypeScript cheatsheet for guidance on [your specific situation](https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/hooks#useref).
### Forms & Events
- Type inference should be sufficient in the case of inline event handlers.
- IDE tooling (such as VSCode autocomplete) will offer helpful suggestions for specific event handler types.
- The React/TypeScript cheatsheet has a list of [specific event types](https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/forms_and_events#list-of-event-types).
## Organization of props and attributes
Ordering of components —
- Class definitions
- Component / imports
- Event handlers inside class
HTML Props/attributes order:
- id, class, attributes
- Like properties alphabetized (?)
Directory structure:
- Pages: routable containers
- Shared: components being used/planned to be used in multiple places
- Compositions: components that have a single/limited specific context