WHISPers v2
This is the web client codebase for version 2 of Wildlife Health Information Sharing Partnership event reporting system. WHISPers allows users to enter, discover, and explore wildlife mortality data submitted by partners across North America and verified by trained biologists.
This project was built with Angular and generated with Angular CLI. It also relies on Leaflet, OpenStreetMap, NgxMatSelectSearch and the USGS Search API.
Prerequisite: Please install Angular-CLI by following these instructions.
git clone https://github.com/USGS-WiM/whispers.git
cd whispers
npm install
Note: It is best to run npm install
at least three times as it often takes several runs to successfully install all dependencies.
The three main environments are configured by environment files found at /src/enviroments/
. The API / web services root URL for each environment is stored in these files. Default environment is development at environment.ts
, used by the development server (see below). Test environment at environment.test.ts
is used by the test build (see below). Production environment at environment.prod.ts
is used by the production build (see below).
Run ng serve
for a dev server with live reload. Navigate to http://localhost:4200/
. The app will automatically reload if you change any of the source files. This will use the development environment configuration (environment.ts).
The Compodoc documentation tool is used to generate static documenation of the WHISPers app.
Run npm run compodoc
to generate and run the documentation server. Navigate to http://127.0.0.1:8080
.
The Angular CLI offers a generate tool that makes the creation of some common component types a little easier.
Run ng generate component component-name
to generate a new component. You can also use ng generate
directive
|pipe
|service
|class
|guard
|interface
|enum
|module
.
For styling consistency, please refer to the UI Guidelines at UI_GUIDELINES.md.
When publishing the WHISPers app on the server for either the test phase or the final publishing to production level, a developer must run the Angular CLI build script to create a minimized, optimized package for server distribution. WHISPers has two build configurations: test and production.
To be used when a new release version is ready for cooperator review but not yet ready for production.
Run ng build --configuration=test --base-href [relative path to web server root]
to build the project. The build artifacts will be stored in the dist/
directory. This will use the test environment configuration.
To be used when a release version has passed the testing phase by receiving approval for promotion by the cooperator.
Run ng build --prod --base-href [relative path to web server root]
to build the project. The build artifacts will be stored in the dist/
directory. This will use the production environment configuration.
Note: the main differences between these two configurations are 1) the API root (prod services/database vs test services/database) and 2) the inclusion of Google Analytics for the production configuration.
WIM has established a collaborative development process that aims to ensure the integrity of the release process through stepwise and peer-reviewed code merges passing through a pipeline of protected branches.
master is reserved for fully vetted code for tested and approved features that represents a version that is in production, i.e. published and live for active users.
clone the repository. This should automatically include the master
branch.
create dev branch locally: git checkout -b dev
pull and merge current dev branch : git pull origin dev
create a branch for your work, checking out from dev
. It is strongly suggested that the branch name be the repository issue number that you are working on: git checkout -b [branch name]
Do work
it is recommended you commit and push changes to the branch at least nightly for safekeeping: git push origin [branch name]
when work on your feature or bug is complete, commit changes and then sync your local feature branch with the remote dev branch: git pull origin dev
. This is an important step because the remote dev branch may have been changed while you were working on your local feature branch. This will auto-merge unless you have conflicts. Resolve the conflicts manually if they exist.
push your feature branch, now synced with remote dev branch (see step 6 above) to the remote feature branch: git push origin [branch name]
. Note this is exactly the same command as step 5. This step is for when you have completed the feature/fix, and pulled/merged the remote dev branch.
In Github, create a Pull Request from your feature branch to the dev
branch. Your peers will review your changes, and comment, and/or approve and merge. You may also be asked to make a change. When all is well, your feature branch will be merged with dev
and the feature branch deleted.
After going to dev
and possibly combined with other commits, the work will be packaged as part of a release tag and distribution build and merged with test
and published to the test server.
Blake Draper - Lead Developer - USGS Web Informatics & Mapping
Lauren Privette - Developer - USGS Web Informatics & Mapping
Nick Estes - Developer - USGS Web Informatics & Mapping
Mitch Samuels - Designer/Developer - USGS Web Informatics & Mapping
See also the list of contributors who participated in this project.
This software is in the Public Domain. See the LICENSE.md file for details
In the spirit of open source, please cite any re-use of the source code stored in this repository. Below is the suggested citation:
This project contains code produced by the Web Informatics and Mapping (WIM) team at the United States Geological Survey (USGS). As a work of the United States Government, this project is in the public domain within the United States. https://wim.usgs.gov
USGS Search API and the Geospatial Science + Cyber Innovation Branch of The USGS Texas Water Science Center
This project authored by the USGS WIM team
WIM is a team of developers and technologists who build and manage tools, software, web services, and databases to support USGS science and other federal government cooperators.
WIM is a part of the Upper Midwest Water Science Center.