mirror of
https://github.com/DOI-DO/j40-cejst-2.git
synced 2025-02-20 08:41:26 -08:00
Update documentation from OS contributors (#1657)
* Update documentation from OS contributors * Disable markdown links checks for certain links * Disable expired links
This commit is contained in:
Vim
GitHub
parent
88c86fcf7c
commit
6ba17b544d
12 changed files with 90 additions and 41 deletions
|
|
@ -1,15 +1,15 @@
|
|||
# Contributor Code of Conduct
|
||||
|
||||
*[¡Lea esto en español!](CODE_OF_CONDUCT-es.md)*
|
||||
_[¡Lea esto en español!](CODE_OF_CONDUCT-es.md)_
|
||||
|
||||
As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
|
||||
|
||||
We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
|
||||
We are committed to making participation in this project a harassment-free experience for everyone, regardless of the level of experience, gender, gender identity, expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
|
||||
|
||||
Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct.
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct.
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers at justice40open@usds.gov.
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)
|
||||
This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)
|
||||
|
|
@ -1,34 +1,35 @@
|
|||
# Justice40 Open Source Community Guidelines
|
||||
|
||||
This document contains principles and guidelines for participating in the Justice40 open source community.
|
||||
This document contains principles and guidelines for participating in the Justice40 open source community.
|
||||
|
||||
## Principles
|
||||
These principles guide our data, product, and process decisions, architecture, and approach. We discussed and developed these principles on the Open Source Community Kickoff on May 10, 2021.
|
||||
|
||||
* Open means transparent and participatory.
|
||||
* We take a modular and modern approach to software development.
|
||||
* We build open source software and open source process.
|
||||
* We value ease of implementation.
|
||||
* Fostering community includes building capacity and making our software and processes accessible to participants with diverse backgrounds and skill sets.
|
||||
* Data (and data science) is as important as software and process. We build open data sets where possible.
|
||||
* We strive for transparency for algorithms and places we might be introducing bias.
|
||||
* We prioritize data sets that address community vulnerabilities for programs in Justice40.
|
||||
These principles guide our data, product, and process decisions, architecture, and approach. We discussed and developed these principles at the Open Source Community Kickoff on May 10, 2021.
|
||||
|
||||
- Open means transparent and participatory.
|
||||
- We take a modular and modern approach to software development.
|
||||
- We build open-source software and open-source process.
|
||||
- We value ease of implementation.
|
||||
- Fostering community includes building capacity and making our software and processes accessible to participants with diverse backgrounds and skillsets.
|
||||
- Data (and data science) is as important as software and process. We build open data sets where possible.
|
||||
- We strive for transparency for algorithms and places we might be introducing bias.
|
||||
- We prioritize data sets that address community vulnerabilities for programs in Justice40.
|
||||
|
||||
## Community Guidelines
|
||||
|
||||
All community members are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md).
|
||||
|
||||
Information on contributing to this repository are available in our [Contributing file](CONTRIBUTING.md).
|
||||
Information on contributing to this repository is available in our [Contributing file](CONTRIBUTING.md).
|
||||
|
||||
When participating in Justice40 open source community conversations and spaces, we ask individuals to follow the following guidelines:
|
||||
|
||||
* When joining a conversation for the first time, please introduce yourself by providing a brief intro that includes:
|
||||
* your related organization (if applicable)
|
||||
* your pronouns
|
||||
* disclosure of any current or potential financial interest in this work
|
||||
* your superpower, and how you hope to use it for Justice 40
|
||||
* Embrace a culture of learning, and educate each other. We are all entering this conversation from different starting points and with different backgrounds. There are no dumb questions.
|
||||
* Take space and give space. We strive to create an equitable environment in which all are welcome and able to participate. We hope individuals feel comfortable voicing their opinions and providing contributions, and will do our best to recognize and make space for individuals who may be struggling to find space here. Likewise we expect individuals to recognize when they are taking up significant space and take a step back to allow room for others.
|
||||
* Be present when joining synchronous conversations such as our community chat. Why be here if you're not going to _be here_?
|
||||
* Be respectful.
|
||||
* Default to positive. Assume others' contributions are legitimate and valuable and that they are made with good intention.
|
||||
- When joining a conversation for the first time, please introduce yourself by providing a brief intro that includes:
|
||||
- your related organization (if applicable)
|
||||
- your pronouns
|
||||
- disclosure of any current or potential financial interest in this work
|
||||
- your superpower, and how you hope to use it for Justice 40
|
||||
- Embrace a culture of learning, and educate each other. We are all entering this conversation from different starting points and with different backgrounds. There are no dumb questions.
|
||||
- Take space and give space. We strive to create an equitable environment in which all are welcome and able to participate. We hope individuals feel comfortable voicing their opinions and providing contributions and will do our best to recognize and make space for individuals who may be struggling to find space here. Likewise, we expect individuals to recognize when they are taking up significant space and take a step back to allow room for others.
|
||||
- Be present when joining synchronous conversations such as our community chat. Why be here if you're not going to _be here_?
|
||||
- Be respectful.
|
||||
- Default to positive. Assume others' contributions are legitimate and valuable and that they are made with good intention.
|
||||
|
|
@ -35,7 +35,9 @@ Abra [aquí](https://github.com/usds/justice40-tool/issues/new/choose) un proble
|
|||
En el problema, describa la función que desea, por qué la necesita y cómo debería funcionar esta. Los integrantes del equipo responderán a este lo antes posible.
|
||||
|
||||
### Colaboraciones con código
|
||||
<!-- markdown-link-check-disable -->
|
||||
Si desea colaborar con alguna parte del código base, bifurque el repositorio siguiendo la [siguiente metodología de GitHub para hacer la bifurcación](https://docs.github.com/es/get-started/quickstart/fork-a-repo) *(en inglés)*. Luego, haga los cambios en el código de su propia copia del repositorio (incluya pruebas, si corresponde) y, por último, [envíe una solicitud para incorporar los cambios en el repositorio precedente](https://docs.github.com/es/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) *(en inglés)*. Para poder fusionar una solicitud de incorporación de cambios, las siguientes opciones en este repositorio deben estar habilitadas:
|
||||
<!-- markdown-link-check-disable -->
|
||||
|
||||
* No se permiten las fusiones al proyecto principal `main`; abra una solicitud de incorporación de cambios desde una rama.
|
||||
* Al menos un revisor autorizado debe aprobar la confirmación (en [CODEOWNERS](https://github.com/usds/justice40-tool/tree/main/.github/CODEOWNERS), en inglés, consulte la lista más reciente de estos revisores).
|
||||
|
|
|
|||
|
|
@ -40,8 +40,9 @@ Please open an issue of type "Feature request" [here](https://github.com/usds/ju
|
|||
In the issue, please describe the feature you would like to see, why you need it, and how it should work. Team members will respond to the issue as soon as possible.
|
||||
|
||||
### Code contributions
|
||||
|
||||
<!-- markdown-link-check-disable -->
|
||||
If you would like to contribute to any part of the codebase, please fork the repository [following the Github forking methodology](https://docs.github.com/en/github/getting-started-with-github/quickstart/fork-a-repo). Then, make changes to the code in your own copy of the repository, including tests if applicable, and finally [submit a pull request against the upstream repo.](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) In order for us to merge a pull request, the following checks are enabled within this repo:
|
||||
<!-- markdown-link-check-enable -->
|
||||
|
||||
- Merges to `main` are prohibited - please open a pull request from a branch
|
||||
- Please create a branch name in the format of `<github-username>`/`<issue-number>`-`<kebab-case-description>`. For example vimusds/1069-fix-territory-on-mobile
|
||||
|
|
|
|||
|
|
@ -2,6 +2,8 @@
|
|||
|
||||
This page contains web links to the datasets that are uploaded as part of our data pipeline, if you want to access them directly. Note that this is just a quick reference and the [Data Pipeline README](/data/data-pipeline/README.md) has the comprehensive documentation on all these datasets.
|
||||
|
||||
This page contains web links to the datasets that are uploaded as part of our data pipeline if you want to access them directly. Note that this is just a quick reference and the [Data Pipeline README](/data/data-pipeline/README.md) has comprehensive documentation on all these datasets.
|
||||
|
||||
> Note: These currently aren't updated on any specific cadence, so be aware of this if you know that the dataset you are using might change frequently.
|
||||
|
||||
- Census data, generated by the [Generate Census Github Action](https://github.com/usds/justice40-tool/blob/main/.github/workflows/generate-census.yml): <https://justice40-data.s3.us-east-1.amazonaws.com/data-sources/census.zip>
|
||||
|
|
|
|||
|
|
@ -49,8 +49,10 @@ Si bien se puede usar cualquier IDE, describimos cómo configurar VS Code
|
|||
5. [Live Share Extention Pack](https://github.com/MicrosoftDocs/live-share)
|
||||
|
||||
## Ejecuta el código
|
||||
|
||||
<!-- markdown-link-check-disable -->
|
||||
1. Bifurcar este repositorio y crear un clon local. [Más información](https://docs.github.com/es/github/getting-started-with-github/quickstart/fork-a-repo)
|
||||
<!-- markdown-link-check-enable -->
|
||||
|
||||
1. Si está usando una Mac y Homebrew, abra la terminal y escriba `brew update` y `brew doctor`.
|
||||
|
||||
Para el desarrollo de front-end, lea el [Client README](client/README.md).
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
# Justice40 Tool Installation
|
||||
|
||||
*[¡Lea esto en español!](INSTALLATION-es.md)*
|
||||
_[¡Lea esto en español!](INSTALLATION-es.md)_
|
||||
|
||||
This page documents the installation steps for some of the software needed to work with this project.
|
||||
|
||||
> **NOTE: If you all you want to do is quickly run everything locally to try out the application, go straight to [`QUICKSTART.md`](QUICKSTART.md).**
|
||||
> **NOTE: If all you want to do is quickly run everything locally to try out the application, go straight to [`QUICKSTART.md`](QUICKSTART.md).**
|
||||
|
||||
After the generic installation steps on this page, continue on to one of the following, depending on what you are trying to do:
|
||||
After the generic installation steps on this page, continue to one of the following, depending on what you are trying to do:
|
||||
|
||||
- If you are working with the frontend, see [`client/README.md`](client/README.md).
|
||||
- If you are working with the data pipeline, see [`data/data-pipeline/README.md`](data/data-pipeline/README.md).
|
||||
|
|
@ -25,10 +25,10 @@ Download from [website](https://git-scm.com/download/win)
|
|||
|
||||
## Install Homebrew (MacOS only)
|
||||
|
||||
Homebrew is an easy way to manage software downloads on MacOS. You don't *have* to use it, but we recommend it.
|
||||
Homebrew is an easy way to manage software downloads on MacOS. You don't _have_ to use it, but we recommend it.
|
||||
|
||||
1. First, open your terminal and run `brew -v` to determine whether you have Homebrew installed. If you get a resopnse that looks something like `Homebrew 3.1.9`, you've already got it! If you get nothing back, or an error, continue.
|
||||
2. Open the terminal and copy / paste this command and hit RETURN. Go through the prompts (you will need to grant `sudo` access).
|
||||
1. First, open your terminal and run `brew -v` to determine whether you have Homebrew installed. If you get a response that looks something like `Homebrew 3.1.9`, you've already got it! If you get nothing back, or an error, continue.
|
||||
2. Open the terminal and copy/paste this command and hit RETURN. Go through the prompts (you will need to grant `sudo` access).
|
||||
|
||||
`/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"`
|
||||
|
||||
|
|
@ -36,6 +36,28 @@ Homebrew is an easy way to manage software downloads on MacOS. You don't *have*
|
|||
|
||||
You should regularly run `brew update` and `brew doctor` to make sure your packages are up to date and in good condition.
|
||||
|
||||
### Install Node using NVM
|
||||
|
||||
This will work for both MacOS and Win10. Follow instructions on this [link](https://medium.com/@nodesource/installing-node-js-tutorial-using-nvm-5c6ff5925dd8). Be sure to read through the whole doc to find the sections within each step relevant to you (e.g. if you're using Homebrew, when you get to Step 2 look for the section, "Install NVM with Homebrew").
|
||||
|
||||
If you install NVM using Homebrew, make sure to read the output in terminal after you run `brew install nvm`. You will need to add a few lines to your ~/.bash_profile and perhaps complete a couple other tasks.
|
||||
|
||||
Once you install NVM, don't forget to install Node! This is included in the linked tutorial above.
|
||||
|
||||
After you've downloaded the nvm and the latest node (using the above steps) also install node version 14 by:
|
||||
|
||||
`brew install node@14`
|
||||
|
||||
You should then be able to switch to that version of node by:
|
||||
|
||||
`nvm use 14`
|
||||
|
||||
To validate you are using node 14, type:
|
||||
|
||||
`node -v`
|
||||
|
||||
This should return *Now using node 14.x.x (npm v6.x.x)*
|
||||
|
||||
## IDE set up (Optional)
|
||||
While any IDE can be used, we're outlining how to set up VS Code
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ The Justice40 team is taking a community-first and open source approach to the p
|
|||
|
||||
We know that we can learn from a wide variety of communities, including those who will use or will be impacted by the tool, who are experts in data science or technology, or who have experience in climate, economic,or environmental justice work. We are dedicated to creating forums for continuous conversation and feedback to help shape the design and development of the tool.
|
||||
|
||||
We also recognize capacity building as a key part of involving a diverse open source community. We are doing our best to use accessible language, provide technical and process documents in multiple languages, and offer support to our community members of a wide variety of background and skillsets, directly or in the form of group chats and training. If you have ideas for how we can improve or add to our capacity building efforts and methods for welcoming folks into our community, please let use know in the [Google Group](https://groups.google.com/u/4/g/justice40-open-source) or email us at justice40open@usds.gov.
|
||||
We also recognize capacity building as a key part of involving a diverse open source community. We are doing our best to use accessible language, provide technical and process documents in multiple languages, and offer support to our community members of a wide variety of backgrounds and skillsets, directly or in the form of group chats and training. If you have ideas for how we can improve or add to our capacity building efforts and methods for welcoming folks into our community, please let us know in the [Google Group](https://groups.google.com/u/4/g/justice40-open-source) or email us at justice40open@usds.gov.
|
||||
|
||||
### Community Guidelines
|
||||
Principles and guidelines for participating in our open source community are available [here](COMMUNITY_GUIDELINES.md). Please read them before joining or starting a conversation in this repo or one of the channels listed below.
|
||||
|
|
@ -35,7 +35,7 @@ Our [Google Group](https://groups.google.com/u/4/g/justice40-open-source) is ope
|
|||
|
||||
The core team uses the group to post updates on the program and tech/data issues, and to share the agenda and call for community participation in the community chat.
|
||||
|
||||
Curious about whether to ask a question here as a Github issue or in the Google Group? The general rule of thumb is that issues are for actionable topics related to the tool or data itself (e.g. questions about a specific data set in use, or suggestion for a new tool feature), and the Google Group is for more general topics or questions. If you can't decide, use the google group and we'll discuss there before moving to Github if appropriate!
|
||||
Curious about whether to ask a question here as a Github issue or in the Google Group? The general rule of thumb is that issues are for actionable topics related to the tool or data itself (e.g. questions about a specific data set in use, or suggestion for a new tool feature), and the Google Group is for more general topics or questions. If you can't decide, use the google group and we'll discuss it there before moving to Github if appropriate!
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ If you want to run the entire application locally, see [QUICKSTART.md](QUICKSTAR
|
|||
|
||||
### Advanced Guides
|
||||
|
||||
If you have software experience or more specific use cases, start at [INSTALLATION.md](INSTALLATION.md) for more in depth documentation of how to work with this project.
|
||||
If you have software experience or more specific use cases, start at [INSTALLATION.md](INSTALLATION.md) for more in-depth documentation of how to work with this project.
|
||||
|
||||
### Project Documentation
|
||||
|
||||
|
|
|
|||
|
|
@ -26,6 +26,19 @@ If you install NVM using Homebrew, make sure to read the output in terminal afte
|
|||
|
||||
Once you install NVM, don't forget to install Node! This is included in the linked tutorial above. This will also install `npm` which you need for the steps below.
|
||||
|
||||
After you've downloaded the nvm and the latest node (using the above steps) also install node version 14 by:
|
||||
|
||||
`brew install node@14`
|
||||
|
||||
You should then be able to switch to that version of node by:
|
||||
|
||||
`nvm use 14`
|
||||
|
||||
To validate you are using node 14, type:
|
||||
|
||||
`node -v`
|
||||
|
||||
This should return *Now using node 14.x.x (npm v6.x.x)*
|
||||
#### Install Yarn
|
||||
|
||||
Install yarn if you do not have it yet. Open your terminal and run `sudo npm install -global yarn`. This works on MacOS and Win10. To confirm it is installed, run `yarn -v`. A version number should be returned.
|
||||
|
|
|
|||
|
|
@ -51,7 +51,13 @@ If the file is super big we can just look at the head of the file:
|
|||
|
||||
In order to see the json file in a pretty format, pipe to jq:
|
||||
|
||||
- `tippecanoe-decode d3_313.pbf 3 1 3 | head -40 | jq`
|
||||
- `tippecanoe-decode d3_313.pbf 3 1 3 | jq`
|
||||
|
||||
While to view just a portion of the feature tile (note we're using a high zoom tile in this example):
|
||||
|
||||
- `tippecanoe-decode d3_9_138_206.pbf 9 138 206 | jq .features | head -100`
|
||||
|
||||
This will filter the decoded pbf by the `features` key and then show the first element in the feature array.
|
||||
|
||||
When the map is clicked, the data (aka features - which are sets of properties in the geojson file ) of the map are able to be accessed via the MapEvent. See [j40Map.tsx](https://github.com/usds/justice40-tool/blob/main/client/src/components/J40Map.tsx)'s `onClick` method for more details.
|
||||
|
||||
|
|
|
|||
|
|
@ -42,11 +42,11 @@ We provide more detail on these factors below.
|
|||
5. [ArcGIS API for Javascript](https://developers.arcgis.com/javascript/latest/) - v4.18 (12/2020)
|
||||
|
||||
## Not Considered Options
|
||||
|
||||
<!-- markdown-link-check-disable -->
|
||||
- Non-ArcGIS-JS-API Esri [products](https://www.esri.com/en-us/arcgis/products/index) - The focus of this investigation is web APIs that can be incorporated into a website and rendered as part of a cloud-based, modular web-development flow. Additionally, these are not open source.
|
||||
- [Google Maps Platform](https://developers.google.com/maps)/[Bing Maps APIs](https://www.microsoft.com/en-us/maps/choose-your-bing-maps-api) - These mapping are also closed source and proprietary, and do not allow for significant customization or visualization of the sort we would need for this product
|
||||
- [d3.js](https://d3js.org/) - though impressive in its offerings and performance, d3 appears more oriented to more general-purpose infographic use than a mapping-specific product requiring significant GIS-adjacent features. We may consider aspects of D3 for particular chart renderings.
|
||||
|
||||
<!-- markdown-link-check-enable -->
|
||||
## Decision Outcome
|
||||
|
||||
**OpenLayers** ([Source](https://github.com/openlayers/openlayers) - v6.5.0 (12/27/20)). This library is completely free and open-source, modular, and modern. As a modern, well-typed and well-documented javascript library, it is approachable, yet offers a full-featured and familiar interface as well for those with a background in GIS systems. As it is free to use, anyone could clone our source and run our project locally without payment or registration. Additionally, it has relatively good performance for large feature sets, despite not using WebGL for rendering.
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@ Others providers:
|
|||
- Many are not open source
|
||||
|
||||
### Data Science Toolkit
|
||||
|
||||
<!-- markdown-link-check-disable -->
|
||||
Data-science-oriented search framework that combines osm with geoip data.
|
||||
|
||||
An overall good option, but if we went down this path we would want to host ourselves -- it is notable that it does give this option.
|
||||
|
|
@ -120,7 +120,7 @@ An overall good option, but if we went down this path we would want to host ours
|
|||
- Cons:
|
||||
- Recommended that you host your own given these limitations
|
||||
- Not recommended for production use
|
||||
|
||||
<!-- markdown-link-check-enable -->
|
||||
### Census Geocoding Services
|
||||
|
||||
Geocoding service provided directly by the census. More info [here](https://www.census.gov/programs-surveys/geography/technical-documentation/complete-technical-documentation/census-geocoder.html).
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue