Merge pull request #621 from hackforla/docs/branch-environments

Update documentation

mkdocs/docs/developer/git-branch-structure.md

@@ -0,0 +1,38 @@
+# GitHub Repo Branch Structure
+
+## Summary
+
+There are three protected branches in our github repo: `main`, `develop`, and `ava-main-v1`.
+
+The two core branches we will use to develop with are  `main` and `develop`. We will use a multi-branching model to collaborate effectively. You can read more about it here: [A successful Git branching model » nvie.com](https://nvie.com/posts/a-successful-git-branching-model/).
+
+The branch `ava-main-v1` is archived for historical purposes.
+
+## What are the `main` and `develop` branches?
+
+The `main` branch is the **core branch in which production code resides**. This is the branch that houses the code that will get deployed to the production environment and delivered to real live users. It is extremely important to make sure this branch is 100% functional, tested and bug-free.
+
+The `develop` branch is the branch we use to stage new features and changes to the code, before pushing it to production. We use this branch to test new code inside a staging environment before delivering it to production.
+
+Developers should create feature branches off of the `develop` branch, then make a pull request from that new feature branch into the `develop` branch. For example: `feature/mybutton-component` gets branched off `develop`, worked on in a dev's local machine, then pushed up the origin repo, and finally pull requested back into the `develop` branch.
+
+Once all the new code in the `develop` branch passed all checks and tests, it should be merged into the `main` branch. This will finally deliver the new code to end users.
+
+If you are still confused, please read the link or watch the youtube video in Additional Resources below for more details. It explains everything much more clearly. Also feel free to ask anyone on the team how it all works.
+
+## What is the V1 branch?
+
+To understand the branch `ava-main-v1`, we need a quick background on the history of this project for context.
+
+Ava Li was the first Technical Project Lead of CivicTechJobs. She initiated the project and wrote all the frontend and backend code. Before she left, she migrated the entire project from plain python to poetry. This broke a lot of things in the backend.
+
+Jimmy Juarez was the next Technical Project Lead. Since the backend wasn't working, he decided to reset the entire django backend. This split the codebase from version 1: pre backend reset, to version 2: post backend reset.
+
+Ava and her team's pre-backend reset code is preserved in the branch `ava-main-v1`. This way their work is not lost, and if we ever need to implement a feature they already did before, we can always look back and study their code. This is the purpose of `ava-main-v1`.
+
+For example, they had implemented a super linter for python and javascript, which does not exist in the current code base. So if we ever want to do that, we can see what they did to deliver it.
+
+## Additional Resources
+
+[Getting started with branching workflows, Git Flow and GitHub Flow - YouTube](https://www.youtube.com/watch?v=gW6dFpTMk8s)<br>
+[A successful Git branching model » nvie.com](https://nvie.com/posts/a-successful-git-branching-model/)<br>

mkdocs/docs/developer/installation.md

@@ -51,11 +51,6 @@ While developing, make sure to create new branches off of the `develop` branch.
 </ul>
 </details>
 
-<details>
-<summary>Note on docker `--watch` flag</summary>
-   <p>The `--watch` flag enables hot module reloads during development. This flag requires a later version of Docker Compose(<a href="https://docs.docker.com/compose/how-tos/file-watch/" target="_blank">2.22.0</a>).</p>
-   <p>If you are running into issues or getting errors running `docker compose up --watch`, please make sure you have installed the latest version of Docker and Docker Desktop on your machine.</p>
-</details><br>
 
 <!-- TODO: Fix the linter container  -->
 <!-- 
@@ -85,11 +80,15 @@ This section might answer some of the burning questions you have. If you cannot
 
 Make sure to turn on Docker by opening the Docker program on your desktop.
 
-##### 2. can't find a suitable configuration file in this directory or any parent: not found
+##### 2. Docker error: 'unknown flag: --watch'
+
+The `--watch` flag enables hot module reloads during development. This flag requires a later version of Docker Compose(<a href="https://docs.docker.com/compose/how-tos/file-watch/" target="_blank">2.22.0</a>). If you are running into issues or getting errors running `docker compose up --watch`, please make sure you have installed the latest version of Docker and Docker Desktop on your machine.
+
+##### 3. can't find a suitable configuration file in this directory or any parent: not found
 
 Make sure that your terminal location is in a directory with a `docker-compose.yml` file. And make sure that the file is not hidden.
 
-##### 3. code ERR_SOCKET_TIMEOUT
+##### 4. code ERR_SOCKET_TIMEOUT
 
 This can result for several reasons, such as havin your sockets overloaded. In order to prevent this, the best thing to do is to lower the amount of sockets used when performing npm install. Change this line in `docker/webpack`:
 
@@ -101,7 +100,7 @@ to:
 
 This should allow `docker compose up` to work. Be sure to delete the addition once your image and container is set up.
 
-##### 4. [dependency] not found
+##### 5. [dependency] not found
 
 This sometimes happen when npm did not install successfully. In this scenario, you need to manually install the dependencies inside the container. Generally the command to run a command inside a container is:
 
@@ -111,7 +110,7 @@ In this scenario, the full command would be:
 
 `docker compose run webpack npm install`
 
-##### 5. [webpack-cli] [Error: EACCES: permission denied', open '/code/frontend/templates/frontend/index.html']
+##### 6. [webpack-cli] [Error: EACCES: permission denied', open '/code/frontend/templates/frontend/index.html']
 
 In this case, the `index.html` file has incorrect ownership and/or permissions. To fix this, run the following command in the root directory of the CTJ repository:
 

mkdocs/docs/developer/mkdocs-architecture.md

@@ -10,7 +10,7 @@
 ├── frontend/
 ├── mkdocs/ # Docs
 │   ├── docs/
-│   └── mkdocs.yml # Docs
+│   └── mkdocs.yml
 ├── .dockerignore
 ├── .gitignore
 ├── CONTRIBUTING.md
@@ -101,15 +101,15 @@ The docs are set to automatically deploy to github pages using the `mkdocs-build
 
 ### Github Action for mkdocs deployment
 
-Links to the github action: [Build MkDocs site (develop)](https://github.com/hackforla/CivicTechJobs/actions/workflows/mkdocs-build.yml)
+Links to the github action: [Build MkDocs site](https://github.com/hackforla/CivicTechJobs/actions/workflows/mkdocs-build.yml)
 
 ```yml
-name: Build MkDocs site (develop)
+name: Build MkDocs site
 
 on:
   push:
     branches:
-      - develop
+      - main
     paths:
       - "mkdocs/**/**.md"
       - "mkdocs/mkdocs.yml"
@@ -151,7 +151,7 @@ jobs:
 Workflow Overview
 
 - `name: Build MkDocs site` - The name of this workflow is "Build MkDocs site."
-- `on: push: - develop` - The workflow is triggered when there’s a push to the develop branch. (We will change this to `main` later)
+- `on: push: - main` - The workflow is triggered when there’s a push to the `main` branch.
 - `paths: ...` - The workflow will only run if the files being pushed are Markdown files (`.md`) or the `mkdocs.yml` configuration file inside the mkdocs directory.
 - `workflow_dispatch:` - This allows manual triggering of the workflow via the GitHub Actions interface.
 - `permissions: contents: write` - This grants the action permission to write contents to the repository. It's needed for deploying the site, which requires pushing to the `gh-pages` branch.
@@ -188,7 +188,7 @@ Publish Documentation
 - then it deploys the MkDocs site to GitHub Pages using `mkdocs gh-deploy --force`. The `--force` flag ensures that the contents of the GitHub Pages branch (`gh-pages`) are overwritten with the latest deployment.
 
 ##### Summary
-This workflow automates the process of building and deploying a MkDocs site when changes are pushed to the develop branch. It does the following:
+This workflow automates the process of building and deploying a MkDocs site when changes are pushed to the `main` branch. It does the following:
 
 1. Checks out the repository and configures Git for pushing changes.
 2. Sets up Python and installs the necessary MkDocs dependencies.

mkdocs/docs/developer/mkdocs-edit-instructions.md

@@ -34,12 +34,10 @@ When you are done editing, the next step is to deploy your changes.
 
 When you are satisfied with your edits, make a pull request so that they can be reviewed.
 
-Once the pull request is approved and merged into `develop`, the changes will be automatically deployed to the official CivicTechJobs documentation site (the site you are reading this page in right now). That's it!
+Once the pull request is approved and the code is merged into the `main` branch, the changes will be automatically deployed to the official CivicTechJobs documentation site (the site you are reading this page in right now). That's it!
 
 If anything goes wrong, you can investigate the workflow in the project's [github actions page](https://github.com/hackforla/CivicTechJobs/actions)
 
-**Note**: At the moment, the docs are set to deploy from the `develop` branch, using the github action located in `mkdocs-build.yml`. This means that whenever a file is changed inside the `mkdocs/` directory, and is merged into the `develop` branch on github, the changes will be automatically deployed to the official site hosted on github pages. In the near future we will set it to deploy from the `main` branch.
-
 *Check out our [MkDocs Architecture](mkdocs-architecture.md) page for more details on how it all fits together.*
 
 ### Recap
@@ -49,4 +47,4 @@ To sum it all up, you can make changes in 4 easy steps:
 1. Start the development server using `docker-compose -f docker-compose.docs.yml up --watch`
 2. Make changes to the `.md` files and observe them in `http://localhost:8005`
 3. Open a Pull Request with your new changes
-4. Merge the Pull Request into the `develop` branch
+4. Merge the Pull Request into the `main` branch

mkdocs/mkdocs.yml

@@ -28,6 +28,7 @@ nav:
           - Development Culture: developer/development-culture.md
           - Frontend Architecture: developer/frontend.md
           - GitHub Architecture: developer/github.md
+          - Git branch Structure: developer/git-branch-structure.md
           - Installation Instructions: developer/installation.md
           - MkDocs Architecture: developer/mkdocs-architecture.md
           - MkDocs - Documentation Guide: developer/mkdocs-guide.md