master2main and dev env setup

docs/contribute/code-guide.md

@@ -70,7 +70,7 @@ Ensure that the key is all caps with underscores as separators and is human-legi
 `.properties` files in the `resources/bundles` language folders are used to generate translations for different supported languages. If you add a new string to the system, add the string to the appropriate `.properties` file, and make sure the string is available across `en`, `de`, `es`, `fr`, and `it`. Either provide the English string in all files, or provide the translated string in each one.
 
 #### Customizing copy
-If you are updating a translation for general use, do your PR against the `master` branch. If you are updating a language file to have specific copy associated with a specific platform, do your PR against the specific platform's branch.
+If you are updating a translation for general use, do your PR against the `main` branch. If you are updating a language file to have specific copy associated with a specific platform, do your PR against the specific platform's branch.
 
 ### Java/jsp style
 Initialize variables and type signatures at the abstract/interface level when possible.

docs/contribute/dev-setup.md

@@ -0,0 +1,78 @@
+# Dev Environment Setup
+
+## Prereqs
+You need the following installed on your system:
+* `default-jdk`
+* `build-essential`
+* `maven`
+* `npm`
+* `node`
+* `docker-compose`
+
+## System setup
+1. Run `sudo sysctl -w vm.max_map_count=262144` (A requirement for OpenSearch, it only needs to be run once on your system.)
+1. Run `npm install react-app-rewired`
+1. `git clone` your [forked Wildbook repo](pr-workflow.md#fork-wildbook) (referred to as the **code directory** going forward)
+
+### Code directory setup
+1. In `devops/development/`, create a `.env` file with a copy the contents of `_env.template`. By default, no changes should be needed.
+1. `cd` to the root of the code directory
+1. run `npm install`
+1. run `chmod +x .husky/pre-commit` to enable husky linting
+1. `cd /frontend`
+1. run `npm install` to install all dependencies
+1. create a `.env` for React environment variables.
+    1. Add the public URL: PUBLIC_URL= /react/
+    1. Add the site name: SITE_NAME=Amphibian Wildbook
+
+### Deploy directory setup
+1. Create your **deploy directory**, matching the value of `WILDBOOK_BASE_DIR` in the .env file. The default is `~/wildbook-dev/`)
+1. Create the necessary subdirectories
+```
+wildbook-dev
+|--logs
+|--webapps
+   |--wildbook
+```
+
+### Build war file
+To run Wildbook in the development docker environment, even to try out the software, you need a "war file" which is made by compiling the Wildbook java project.
+
+To create the war file:
+1. `cd` to the root of the code directory
+1. Build your war file with `mvn clean install`
+1. verify the war file was created in `target/wildbook-X.Y.Z.war` (where X.Y.Z is the current version number).
+1. cd to the deploy directory `cd ~/wildbook-dev/webapps/wildbook` 
+1. deploy your warfile `jar -xvf /code/directory/Wildbook/target/wildbook-X.Y.Z.war`
+
+### Deploy
+1. `cd` to the `devops/development` directory in the code repo
+1. run `docker-compose up [-d]`
+1. To verify successful launch, open in browser `http://localhost:81/` when tomcat has started. Default login of username/password `tomcat`/`tomcat123` should work.
+
+Note: if you're running docker as root, you may want to explicitly set your deploy directory path to include your user, i.e., `WILDBOOK_BASE_DIR=~USER/wildbook-dev`
+
+### Redeploy and rebuild
+For any local testing, you will need to rebuild and redeploy your changes.
+
+#### War file
+
+If you make code changes and want to test them locally, you can create and deploy a new war file using the [Build war file](#build-war-file) and [Deploy](#deploy) instructions. Then use `docker-compose restart wildbook` to test your changes.
+
+#### React-only changes
+
+If you are working on react-only work, you can test your changes without updating the full war file.
+Use npm to build and deploy to your local deployment
+
+If you have your dev environment set up correctly, this will build the React app and copy it into your local deployment directory for you.
+
+1. `cd` to `REPO/frontend/`
+1. run `npm run deploy-dev`
+1. refresh your browser page by visiting either http://localhost:81/react/ for local testing or https://public.url.example.com/react/ for the public-facing deployment
+
+#### Manually rebuild react-only changes
+
+1. `cd` to `REPO/frontend/`
+1. run `npm run build`
+1. copy everything under `frontend/build/` to the deployed `wildbook/react/` directory you created during setup
+1. refresh your browser page by visiting either http://localhost:81/react/ for local testing or https://public.url.example.com/react/ for the public-facing deployment

docs/contribute/index.md

@@ -3,6 +3,7 @@
 ```{toctree}
 :hidden:
 
+dev-setup
 pr-workflow
 code-guide
 copy-guide

docs/contribute/pr-workflow.md

@@ -1,6 +1,8 @@
 # Pull Request Workflow
 
-All contributions should be made from a fork off of the Wildbook repo. While there are a number of repositories for specific Wildbook communities, large scale development is driven from the main repository. 
+All contributions should be made from a fork off of the Wildbook repo. While there are a number of repositories for specific Wildbook communities, large scale development is driven from the `main` branch. 
+
+_Note: See [dev environment setup](dev-setup.md) for how to test changes locally._
 
 ## Fork Wildbook
 To start, you will need to be signed in to your GitHub account, have admin access to your OS's terminal, and have Git installed.
@@ -17,30 +19,22 @@ _Note: The same forking process is used for [WildbookExport](https://github.com/
 
 ## Create Local Branch
 You will want to work in a branch when doing any feature development you want to provide to the original project.
-1. Verify you are on the master branch. The branch you have checked out will be used as the base for your new branch, so you typically want to start from master.
-`git checkout master`
+1. Verify you are on the main branch. The branch you have checked out will be used as the base for your new branch, so you typically want to start from main.
+`git checkout main`
 1. Create your feature branch. It can be helpful to include the issue number (ISSUENUMBER) you are working to address.
 `git branch ISSUENUMBER-FEATUREBRANCHNAME`
 1. Change to your feature branch so your changes are grouped together.
 `git checkout ISSUENUMBER-FEATUREBRANCHNAME`
 1. Update your branch (this is not needed if you just created new branch, but is a good habit to get into).
-` git pull upstream master`
-
-_Note: The primary branch you'll be working from for Scout or WildbookExport is `main`._
-
-## Set Up Development Environment with Docker
-For easiest development, you will need to set up your development environment to work with Docker. See `devops/development/README.md` for detailed instructions.
-
-## Deploy frontend
-To setup frontend, we need to deploy the React build to Wildbook, please follow the detailed instructions provided in the `frontend/README.md` file within the project directory.
+` git pull upstream main`
 
 ## Making Local Changes
 Make the code changes necessary for the issue you're working on. The following git commands may prove useful.
 
 * `git log`: lastest commits of current branch
 * `git status`: current staged and unstaged modifications
 * `git diff --staged`:  the differences between the staging area and the last commit
-* `git add <filename>: add files that have changes to staging in preparation for commit
+* `git add <filename>`: add files that have changes to staging in preparation for commit
 * `git commit`: commits the stagged files, opens a text editor for you to write a commit log
 
 ## Submit PR
@@ -59,7 +53,7 @@ Up to this point, all changes have been done to your local copy of Wildbook. You
 At this point, it's on us to get you feedback on your submission! Someone from the Wild Me team will review the project and provide any feedback that may be necessary. If changes are recommended, you'll need to checkout the branch you were working from, update the branch, and make these changes locally.
 
 1. `git checkout ISSUENUMBER-FEATUREBRANCHNAME`
-1. `git pull upstream master`
+1. `git pull upstream main`
 1. Make required changes
 1. `git add <filename>` for all files impacted by changes
 1. Determine which method would be most appropriate for updating your PR  
@@ -69,8 +63,8 @@ At this point, it's on us to get you feedback on your submission! Someone from t
 ## Other branches
 The code for specific Wildbook platforms is available in different branches under the Wildbook repo. The only contributions made to these repos are:
 * standardizations by the Wild Me team to get rid of historical custom code
-* merges of master into the branch by the Wild Me team
+* merges of main into the branch by the Wild Me team
 * updates to `.properties` files, such as translations, custom fields, or species management
 * updates to `IA.json` to manage locationIDs available in the system
 
-All custom feature work that is pushed to a non-`master` branch will be closed unless discussed and approved by the Wild Me team in advance.
+All custom feature work that is pushed to a non-`main` branch will be closed unless discussed and approved by the Wild Me team in advance.