Simplify contributing

.pre-commit-config.yaml

@@ -141,7 +141,6 @@ repos:
         exclude: |
           (?x)^(
             .github/ISSUE_TEMPLATE/|
-            docs/CONTRIBUTING.md$|
             docs/index.md$|
             docs/license.md$
           )

README.md

@@ -38,7 +38,7 @@ This repository uses the [GNU General Public License (v2.0)][licensing].
 
 <!-- References section -->
 
-[contributing]: ./CONTRIBUTING.md
+[contributing]: http://hackforla.github.io/peopledepot/contributing/
 [django-docs]: https://docs.djangoproject.com/
 [docker-docs]: https://www.postgresql.org/docs/
 [drf-docs]: https://www.django-rest-framework.org/tutorial/quickstart/

app/Dockerfile

@@ -5,8 +5,8 @@ FROM python:3.10-alpine
 WORKDIR /usr/src/app
 
 # set environment variables
-ENV PYTHONDONTWRITEBYTECODE 1
-ENV PYTHONUNBUFFERED 1
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
 ENV PYTHONPYCACHEPREFIX=/root/.cache/pycache/
 
 # install system dependencies

docker-compose.yml

@@ -1,5 +1,3 @@
-version: '3.8'
-
 services:
   web:
     build: ./app

docs/.pages

@@ -1,11 +1,7 @@
 nav:
   - index.md
-  - Get Started:
-    - CONTRIBUTING.md
   - architecture
   - ref
   - howto
-  - how-to
-  - tools
-  - ...
+  - contributing
   - license.md

docs/contributing/.pages

@@ -0,0 +1,9 @@
+nav:
+  - team.md
+  - dev_environment.md
+  - issues.md
+  - git.md
+  - documentation.md
+  - howto
+  - ...
+  - tools

docs/contributing/dev_environment.md

@@ -0,0 +1,176 @@
+# Development Environment
+
+## Pre-requisites
+
+### GitHub account
+
+See [here](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account#signing-up-for-a-new-account) for creating a GitHub account. If you are not familiar with Git, [this tutorial](https://docs.github.com/en/get-started/quickstart/hello-world) is recommended.
+
+### Two-factor authentication
+
+Set up two-factor authentication on your account by following this [guide](https://docs.github.com/en/github/authenticating-to-github/configuring-two-factor-authentication).
+
+### Text editor
+
+[VS Code](https://code.visualstudio.com/download) is recommended, but feel free to use a text editor of your choice.
+
+### Install Git
+
+Before cloning your forked repository to your local machine, you must have Git installed. You can find instructions for installing Git for your operating system [**here**](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+
+=== "Windows"
+    - we recommend [installing Windows Subsystem for Linux (WSL)](https://code.visualstudio.com/docs/remote/wsl). WSL provides a Linux-compatible environment that can prevent common errors during script execution.
+
+    - After setting up WSL, install Git directly from the Linux terminal. This method can help avoid complications that sometimes arise when using Git Bash on Windows.
+
+    - If you prefer Git Bash or encounter errors related to line endings when running scripts, the problem might be due to file conversions in Windows. To address this, configure Git as follows:
+
+        ```bash
+        git config --system set autocrlf=false
+        ```
+
+        !!! tip "Feel free to reach out in the [Hack for LA Slack channel](https://hackforla.slack.com/messages/people-depot/) if you encounter any errors while running scripts on Windows"
+
+=== "Mac"
+    Please note that if you have a Mac the page offers several options (see other option, if you need to conserve hard drive space) including:
+
+    - an “easiest” option (this version is fine for our use): This option would take just over 4GB.
+    - a “more up to date” option (not required but optional if you want it): This option prompts you to go to install an 8GB package manager called Homebrew.
+    - Other option: If your computer is low on space, you can use this [tutorial](https://www.datacamp.com/community/tutorials/homebrew-install-use) to install XCode Command Tools and a lighter version of Homebrew and then install Git using this command: `$ brew install git` which in total only uses 300MB.
+
+### Install Docker
+
+Install or make sure [docker][docker-install] and [docker-compose][docker-compose-install] are installed on your computer
+
+```bash
+docker -v
+docker-compose -v
+```
+
+The recommended installation method for your operating system can be found [here](https://docs.docker.com/install/).
+
+!!! tip "Feel free to reach out in the [Hack for LA Slack channel](https://hackforla.slack.com/messages/people-depot/) if you have trouble installing docker on your system"
+
+More on using Docker and the concepts of containerization:
+
+- [Get started with Docker](https://docs.docker.com/get-started/)
+
+## Fork the repository
+
+You can fork the hackforla/peopledepot repository by clicking <a href="https://github.com/hackforla/peopledepot/fork"> <button> <img src="https://user-images.githubusercontent.com/17777237/54873012-40fa5b00-4dd6-11e9-98e0-cc436426c720.png" width="8px"> Fork</button></a>
+. A fork is a copy of the repository that will be placed on your GitHub account.
+
+!!! note "It should create a URL that looks like the following -> `https://github.com/<your_GitHub_user_name>/peopledepot`"
+    !!! example "For example -> `https://github.com/octocat/peopledepot`"
+
+!!! info "What you have created is a forked copy in a remote version on GitHub. It is not on your local machine yet"
+
+### Clone a copy on your computer
+
+The following steps will clone (create) a local copy of the forked repository on your computer.
+
+1. Create a new folder in your computer that will contain `hackforla` projects.
+
+    In your command line interface (Terminal, Git Bash, Powershell), move to where you want your new folder to be placed and create a new folder in your computer that will contain `hackforla` projects. After that, navigate into the folder(directory) you just created.
+
+    For example:
+
+    ```bash
+    cd /projects
+    mkdir hackforla
+    cd hackforla
+    ```
+
+1. From the hackforla directory created in previous section:
+
+    ```bash
+    git clone https://github.com/<your_GitHub_user_name>/peopledepot.git
+    ```
+
+    For example if your GitHub username was `octocat`:
+
+    ```bash
+    git clone https://github.com/octocat/peopledepot.git
+    ```
+
+    !!! note "You can also clone using ssh which is more secure but requires more setup. Because of the additional setup, cloning using https as shown above is recommended"
+
+You should now have a new folder in your `hackforla` folder called `peopledepot`. Verify this by changing into the new directory:
+
+```bash
+cd peopledepot
+```
+
+### Verify and set up remote references
+
+Verify that your local cloned repository is pointing to the correct `origin` URL (that is, the forked repo on your own GitHub account):
+
+```bash
+git remote -v
+```
+
+You should see `fetch` and `push` URLs with links to your forked repository under your account (i.e. `https://github.com/<your_GitHub_user_name>/peopledepot.git`). You are all set to make working changes to the project on your local machine.
+
+However, we still need a way to keep our local repo up to date with the deployed project. To do so, you must add an upstream remote to incorporate changes made while you are working on your local repo. Run the following to add an upstream remote URL & update your local repo with recent changes to the `hackforla` version:
+
+```bash
+git remote add upstream https://github.com/hackforla/peopledepot.git
+git fetch upstream
+```
+
+After adding the upstream remote, you should now see it if you again run `git remote -v` :
+
+```bash
+origin  https://github.com/<your_GitHub_user_name>/peopledepot.git (fetch)
+origin  https://github.com/<your_GitHub_user_name>/peopledepot.git (push)
+upstream        https://github.com/hackforla/peopledepot.git (fetch)
+upstream        https://github.com/hackforla/peopledepot.git (push)
+```
+
+## Build and run using Docker locally
+
+1. Make sure the Docker service is running
+
+    === "Docker (Engine)"
+        ```bash
+        sudo systemctl status docker
+        ```
+
+        It will show `Active: active (running)` if it's running.
+
+    === "Docker Desktop"
+        1. Start Docker Desktop
+        1. Run `docker container ls` to verify Docker Desktop is running. If it is not running you will get the message: `Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?`
+
+1. Create an .env.docker file from .env.docker-example
+
+    ```bash
+    cp ./app/.env.docker-example ./app/.env.docker
+    ```
+
+1. Build and run the project via the script (this includes running `docker-compose up`)
+
+    ```bash
+    ./scripts/buildrun.sh
+    ```
+
+1. Create a super user for logging into the web admin interface
+
+    ```bash
+    docker-compose exec web python manage.py createsuperuser --no-input
+    ```
+
+1. Browse to the web admin interface at `http://localhost:8000/admin/` and confirm the admin site is running. Use DJANGO_SUPERUSER_USERNAME and DJANGO_SUPERUSER_PASSWORD from .env.docker for credentials.
+
+See our documentation for [Working with Docker](tools/docker.md#working-with-docker) for more useful Docker commands.
+
+## Install pre-commit
+
+This will check your changes for common problems.
+
+See the [Pre-commit page](tools/pre-commit.md) for installation instructions.
+
+For consistency, an automated bot will perform the same checks on the repository side when you open a pull request.
+
+[docker-compose-install]: https://docs.docker.com/compose/install/
+[docker-install]: https://docs.docker.com/get-docker/

docs/contributing/documentation.md

@@ -0,0 +1,5 @@
+# Documentation
+
+We highly encourage contributors to add and update documentation in the same pull request as the code. This will ensure that the docs and features are synchronized.
+
+Please see the [MkDocs page](tools/mkdocs.md) for how to view documentation changes locally using the mkdocs in docker.

docs/contributing/git.md

@@ -0,0 +1,37 @@
+# Working with Git
+
+## Sync Main Changes
+
+Your fork of this repository on GitHub, and your local clone of that fork, will get out of sync with the (upstream) repository as others update the repository. (That's what has happened when you see something like "This branch is 1 commit behind peopledepot:main" on your forked repository.)
+
+One way to keep your fork up to date with this repository is to follow these instruction: [Syncing your fork to the original repository via the browser](https://github.com/KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser)
+
+You can also update your fork via the local clone of your fork, using these instructions. Assuming you have a local clone with remotes `upstream` (this repo) and `origin` (your GitHub fork of this repo):
+
+- First, you will need to create a local branch which tracks upstream/main. You will only need to do this once; you do not need to do this every time you want to incorporate upstream changes.
+
+Run the following two commands:
+
+```bash
+git fetch upstream
+git checkout -b upstream-main --track upstream/main
+```
+
+If you have already created the branch upstream-main, the following commands will incorporate upstream changes:
+
+```bash
+git checkout upstream-main # Move to the branch you want to merge with.
+git pull  # This updates your tracking branch to match the main branch in this repository
+git checkout main  # Move back to your main branch
+git merge upstream-main  # Merge to bring your main current.
+```
+
+If you do all your work on topic branches (as suggested above) and keep main free of local modifications, this merge should apply cleanly.
+
+Then push the merge changes to your GitHub fork:
+
+```bash
+git push
+```
+
+If you go to your online GitHub repository this should remove the message "This branch is x commit behind peopledepot:main".

docs/contributing/howto/.pages

@@ -0,0 +1,6 @@
+title: How-to Guides
+nav:
+  - add-model-and-api-endpoints.md
+  - create-initial-data-migrations.md
+  - run-local.md
+  - ...

docs/how-to/add-model-and-api-endpoints.md → docs/contributing/howto/add-model-and-api-endpoints.md

@@ -13,7 +13,7 @@ This guide aims to enable developers with little or no django experience to add
     - API design
     - command line
 
-This guide assumes the developer has followed the [contributing doc](CONTRIBUTING.md) and have forked and created a local branch to work on this. The development server would be already running in the background and will automatically apply the changes when we save the files.
+This guide assumes the developer has followed the [working with issues guide](issues.md) and have forked and created a local branch to work on this. The development server would be already running in the background and will automatically apply the changes when we save the files.
 
 We will choose the [recurring_event issue](https://github.com/hackforla/peopledepot/issues/14) as an example. Our goal is to create a database table and an API that a client can use to work with the data. The work is split into 3 testable components: the model, the admin site, and the API
 
@@ -205,7 +205,7 @@ In `app/core/admin.py`
 
 Check that everything's working and there are no issues, which should be the case unless there's custom input fields creating problems.
 
-1. See the [contributing doc section on "Build and run using Docker locally"](CONTRIBUTING.md#23-build-and-run-using-docker-locally) for how to view the admin interface.
+1. See the [development setup guide section on "Build and run using Docker locally"](dev_environment.md#build-and-run-using-docker-locally) for how to view the admin interface.
 
 1. Example of a custom field (as opposed to the built-in ones)
 
@@ -441,10 +441,10 @@ In `app/core/api/urls.py`
 
     1. Params
         1. First param is the URL prefix use in the API routes. It is, by convention, plural
-            - This would show up in the URL like this: `http://localhost/api/v1/recuring-events/` and `http://localhost/api/v1/recuring-events/<uuid>`
+            - This would show up in the URL like this: `http://localhost:8000/api/v1/recuring-events/` and `http://localhost:8000/api/v1/recuring-events/<uuid>`
         1. Second param is the viewset class which defines the API actions
         1. `basename` is the name used for generating the endpoint names, such as <basename>-list, <basename>-detail, etc. It's in the singular form. This is automatically generated if the viewset definition contains a `queryset` attribute, but it's required if the viewset overrides that with the `get_queryset` function
-            - `reverse("recurring-event-list")` would return `http://localhost/api/v1/recuring-events/`
+            - `reverse("recurring-event-list")` would return `http://localhost:8000/api/v1/recuring-events/`
 
 ??? note "Test"
     For the CRUD operations, since we're using `ModelViewSet` where all the actions are provided by `rest_framework` and well-tested, it's not necessary to have test cases for them. But here's an example of one.
@@ -508,4 +508,4 @@ In `app/core/api/urls.py`
         ```
 
 ??? note "Push the code and start a PR"
-    Refer to the [contributing doc section on "Push to upstream origin"](CONTRIBUTING.md#410-push-to-upstream-origin-aka-your-fork) onward.
+    Refer to the [Issues page section on "Push to upstream origin"](issues.md#push-to-upstream-origin-aka-your-fork) onward.

docs/contributing/howto/index.md

@@ -0,0 +1,7 @@
+# How-to Guides
+
+These are the developer guides for how to do specific things with the project.
+
+1. [Add model and API endpoints](add-model-and-api-endpoints.md)
+1. [Create initial data migrations](create-initial-data-migrations.md)
+1. [Run the project in a virtual environment](run-local.md)

docs/contributing/index.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Thank you for volunteering your time! The following is a set of guidelines for contributing to the PeopleDepot repository, which is hosted on GitHub.
+
+**Please make sure you have completed the onboarding process which includes joining the Hack for LA Slack, GitHub, and Google Drive. If you have not been onboarded, see the [Getting Started Page](https://www.hackforla.org/getting-started).** _Workshop attendees are granted a temporary exception from this requirement._
+
+- [Joining the team](team.md)
+
+- [Setting up the Development Environment](dev_environment.md)
+
+    - [Pre-requisites](dev_environment.md#pre-requisites)
+    - [Fork the repository](dev_environment.md#fork-the-repository)
+    - [Build and run locally](dev_environment.md#build-and-run-using-docker-locally)
+
+- [Working with Issues](issues.md)
+
+- [Working with Git](git.md)
+
+- [Documentation](documentation.md)
+
+- [How-to Guides](howto/index.md)
+
+- [Tools](tools/index.md)