Update docs with the latest info for environments

Update local dev env page - Add forking - Update descriptions Update production deployment page - Add cloning fork to dev env page - Add pre-commit commands - Add docs badge to README.md - Add supervisor setup Update backend dev page - Add commands for Django migrations Update project standards page - Update descriptions and formatting - Add pre-commit commands - Add how to squash and rebase commits Update prod page
esgf2-us · Mar 4, 2021 · ae9e88b · ae9e88b
1 parent 882e138
commit ae9e88b
Show file tree

Hide file tree

Showing 8 changed files with 384 additions and 85 deletions.
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 Earth System Grid Federation's (ESGF) next generation search portal.
 If you are a new contributor or just want to learn more, please visit the [documentation site](https://metagrid.readthedocs.io/en/latest/).
 
-[![Pre-commit Checks](https://github.com/aims-group/metagrid/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/aims-group/metagrid/actions/workflows/pre-commit.yml) ![Front-end CI](https://github.com/aims-group/metagrid/workflows/Front-end%20CI/badge.svg) ![Back-end CI](https://github.com/aims-group/metagrid/workflows/Back-end%20CI/badge.svg)
+[![Pre-commit Checks](https://github.com/aims-group/metagrid/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/aims-group/metagrid/actions/workflows/pre-commit.yml) ![Front-end CI](https://github.com/aims-group/metagrid/workflows/Front-end%20CI/badge.svg) ![Back-end CI](https://github.com/aims-group/metagrid/workflows/Back-end%20CI/badge.svg) [![Documentation Status](https://readthedocs.org/projects/metagrid/badge/?version=latest)](https://metagrid.readthedocs.io/en/latest/?badge=latest)
 [![Codecov Coverage](https://codecov.io/gh/aims-group/metagrid/branch/master/graph/badge.svg)](https://codecov.io/gh/aims-group/metagrid/) [![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com/)
 
 ## Front-end

diff --git a/docs/docs/contributors/backend_development.md b/docs/docs/contributors/backend_development.md
@@ -211,6 +211,39 @@ Run a command inside the docker container:
 docker-compose -p metagrid_backend_dev run --rm django [command]
 ```
 
+### Django migrations
+
+Make migrations
+
+```bash
+python manage.py makemigrations your_app_name
+```
+
+- You specify the app using `your_app_name`, or omit to run on all
+
+Make data migration
+
+- https://docs.djangoproject.com/en/3.1/topics/migrations/#data-migrations
+- Useful for changing the data in the database itself, in conjunction with the schema if you want
+
+```bash
+python manage.py makemigrations --empty your_app_name
+```
+
+Show migrations
+
+```bash
+python manage.py showmigrations
+```
+
+Run migrations
+
+```bash
+python manage.py migrate your_app_name
+```
+
+- You specify the app using `your_app_name`, or omit to run on all
+
 ### Creating a Superuser
 
 Useful for logging into Django Admin page to manage the database
@@ -269,7 +302,6 @@ mypy metagrid
 
 ### Linting
 
-
 ```bash
 flake8 .
 ```

diff --git a/docs/docs/contributors/getting_started_local.md b/docs/docs/contributors/getting_started_local.md
@@ -1,7 +1,5 @@
 # Getting Started for Local Development
 
-Carefully follow the steps below for a smooth experience.
-
 !!! note
 
     If you're new to Docker, please be aware that some resources are cached system-wide
@@ -14,27 +12,58 @@ Carefully follow the steps below for a smooth experience.
 - [docker-compose](https://docs.docker.com/compose/install/)
 - Python >= 3.8 to create virtual environment for `pre-commit` package
 
-## 1. Set up `pre-commit`
+## 1. Clone your fork and keep in sync with upstream `master`
+
+```bash
+git clone https://github.com/<your-github-username>/metagrid.git
+```
+
+Rebase your fork with upstream to keep in sync
+
+```bash
+# Add the remote, call it "upstream":
+git remote add upstream https://github.com/aims-group/metagrid.git
+
+# Fetch all the branches of that remote into remote-tracking branches
+git fetch upstream
+
+# Make sure that you're on your master branch:
+git checkout master
+
+# Rewrite your master branch so that any of your commits that
+# aren't already in upstream/master are replayed on top of the
+# other branch:
+git rebase upstream/master
+git push -f origin master
+```
+
+Checkout a new branch from `master`.
+
+```bash
+git checkout -b <branch-name> master
+```
+
+## 2. Set up `pre-commit`
 
 This repo has default integration with [pre-commit](https://pre-commit.com/), a tool for identifying simple issues before submission to code review. These checks are performed for all staged files using `git commit` before they are committed to a branch.
 
-### 1.1 Integrated Hooks (Quality Assurance Tools)
+### 2.1 Integrated Hooks (Quality Assurance Tools)
 
 | Platform              | Code Formatter                                   | Linter                                           | Type Checker                  |
 | --------------------- | ------------------------------------------------ | ------------------------------------------------ | ----------------------------- |
 | Python                | [black](https://black.readthedocs.io/en/stable/) | [flake8](https://github.com/PyCQA/flake8#flake8) | [mypy](http://mypy-lang.org/) |
 | JavaScript/TypeScript | [prettier](https://prettier.io/)                 | [ESLint](https://eslint.org/)                    | N/A                           |
 
-### 1.2 Install
+### 2.2 Install
 
 ```bash
-cd backend
 
-# Create a python3 virtual environment using system-level Python
-python3 -m venv venv
+# Create a python3 virtual environment using system-level Python.
+# There may be alternative ways for you to do this.
+python3 -m venv backend/venv
 
 # Activate the virtual environment
-source venv/bin/activate
+source backend/venv/bin/activate
 
 # Install local requirements
 pip install -r requirements/local.txt
@@ -45,43 +74,42 @@ pre-commit install
 
 **Note: any update to `.pre-commit.config.yaml` requires a reinstallation of the hooks**
 
-### Helpful Commands
+### 2.3 Helpful Commands
 
-#### Automatically run all pre-commit hooks -- just commit
+Automatically run all pre-commit hooks (just commit)
 
 ```bash
 git commit -m '...'
 ```
 
-#### Manually run all pre-commit hooks
+![Pre-commit Output](../images/pre-commit-passing.png)
+
+Manually run all pre-commit hooks
 
 ```bash
 pre-commit run --all-files.
 ```
 
-#### Run individual hook
+Run individual hook
 
 ```bash
+# Available hook ids: trailing-whitespace, end-of-file-fixer, check-yaml, black, isort, flake8, mypy
 pre-commit run <hook_id>.
 ```
 
-Available hook ids: `trailing-whitespace`, `end-of-file-fixer`, `check-yaml`, `black`, `isort`, `flake8`, `mypy`
-
-## 2. Set up Back-end
+## 3. Set up Back-end
 
 Open the project in a terminal and `cd backend`.
 
-### 2.1 Build and Run the Stack
+### 3.1 Build and Run the Stack
 
 This can take a while, especially the first time you run this particular command on your development system but subsequent runs will occur quickly:
 
 ```bash
 docker-compose -p metagrid_backend_dev up --build
 ```
 
-Remove the `--build` flag when you don't need to rebuild (e.g. no updates to Docker/docker-compose related files).
-
-### 2.2 Additional Configuration
+### 3.2 Additional Configuration
 
 #### Update `/etc/hosts` file
 
@@ -102,14 +130,14 @@ This user will be used for logging into registered Keycloak clients, including t
 2. Login with admin credentials (automatically created)
    - username: admin
    - password: admin
-3. Follow the rest of the instructions in the official Keycloak guide to [create a new user](https://www.keycloak.org/docs/latest/getting_started/#creating-a-user)
+3. Follow the official Keycloak instructions to [create a new user](https://www.keycloak.org/docs/latest/getting_started/#creating-a-user)
 
-### 2.3 Accessible Services
+### 3.3 Accessible Services
 
 - Django: `localhost:8000`
 - Keycloak: `localhost:8080`/`keycloak:8080`
 
-### 2.4 Troubleshooting
+### 3.4 Troubleshooting
 
 #### Addressing Keycloak Boot Issue
 
@@ -137,21 +165,19 @@ Source:
 - [https://issues.redhat.com/browse/KEYCLOAK-12896](https://issues.redhat.com/browse/KEYCLOAK-12896)
 - [https://stackoverflow.com/a/59712689/8023435](https://stackoverflow.com/a/59712689/8023435)
 
-## 3. Set up Front-end
+## 4. Set up Front-end
 
 Open the project in a terminal and `cd frontend`.
 
-### 3.1 Build and Run the Stack
+### 4.1 Build and Run the Stack
 
 This can take a while, especially the first time you run this particular command on your development system but subsequent runs will occur quickly:
 
 ```bash
 docker-compose -p metagrid_frontend_dev up --build
 ```
 
-Remove the `--build` flag when you don't need to rebuild (e.g. no updates to Docker/docker-compose related files).
-
-### 3.2 Accessible Services
+### 4.2 Accessible Services
 
 - React: `localhost:3000`
 
@@ -166,3 +192,5 @@ Remove the `--build` flag when you don't need to rebuild (e.g. no updates to Doc
 Code coverage: [![Codecov Coverage](https://codecov.io/gh/aims-group/metagrid/branch/master/graph/badge.svg)](https://codecov.io/gh/aims-group/metagrid/)
 
 Dependency Monitoring: [![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com/) [![Updates](https://pyup.io/repos/github/aims-group/metagrid/shield.svg)](https://pyup.io/repos/github/aims-group/metagrid/)
+
+Docs: [![Documentation Status](https://readthedocs.org/projects/metagrid/badge/?version=latest)](https://metagrid.readthedocs.io/en/latest/?badge=latest)