Skip to content

Commit 5f47a78

Browse files
lpatmolpatmo
committed
Update contributing.md
1 parent 4842d2f commit 5f47a78

File tree

1 file changed

+170
-120
lines changed

1 file changed

+170
-120
lines changed

‎contributing.md

+170-120
Original file line numberDiff line numberDiff line change
@@ -1,190 +1,240 @@
1-
## **Contributing CodeBuddies website version 3 (CBV3)**
1+
## Getting started
22

3-
## **Setup**
3+
We recommend you run CodeBuddies locally using Docker. We assume you have Docker installed, but if not please [install Docker for your operating system](https://docs.docker.com/desktop/).
44

5-
Although it is possible to run the website locally, we recommend you run CodeBuddies locally using [Docker](https://www.docker.com/get-started).
5+
These instructions have been used on the following operating systems.
66

7-
These instructions have been used on the following operating systems:
8-
* Linux
9-
* Mac OS
10-
* Windows 10 Pro (Windows 10 Home is supported by Docker Desktop at the moment)
7+
- [Linux Docker installation guide](https://docs.docker.com/engine/install/ubuntu/)
8+
- [Mac OS Docker installation guide](https://docs.docker.com/docker-for-mac/install/)
9+
- [Windows 10 Pro Docker installion guide](https://docs.docker.com/docker-for-windows/install/)
10+
- [Windows 10 Home Docker installation guide](https://docs.docker.com/docker-for-windows/install-windows-home/)
1111

12-
### Fundamental Knowledge
12+
## Development Environment Setup
13+
1. Fork this repository. This creates a copy of the repository for you to work on. For more help see this GitHub guide: [Fork a repo].
1314

14-
Contributors are expected to have fundamental knowledge of the [technologies used for CBV3](README.md#technologies-used).
15+
2. Clone your fork. This creates a copy on your local computer. For more help see this GitHub guide: [Cloning a repository].
1516

16-
#### Steps
17+
```bash
18+
$ git clone https://github.com/codebuddies/backend codebuddies-backend
19+
```
1720

18-
Docker is expected to be installed before the website is deployed. Follow the guide [here](https://www.docker.com/products/docker-desktop) to install it if you have not done so.
21+
3. Navigate into the project directory.
1922

20-
1. Fork this repository. See [Fork a repo](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) for help if needed.
21-
2. Clone your fork.
23+
```bash
24+
$ cd codebuddies-backend
25+
```
2226

23-
```plain
24-
git clone [email protected]::codebuddies/backend.git cb-backend
25-
```
26-
Clone the forked repository to your computer using the command `git clone` and save as `cb-backend`. This command works on MacOS and Linux. For details or Windows user, follow the instructions on [Cloning a repository](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository)
27+
4. Run the following docker command to start up the local development environment.
2728

28-
3. Navigate into the project directory
29-
```plain
30-
cd cb-backend
31-
```
29+
```bash
30+
$ docker-compose up -d
31+
```
3232

33-
4. Start the local development environment
33+
**Note:** `-d` starts Docker in detatched mode. See [logs](#debugging-with-docker-logs)
3434

35-
(for Windows users please ensure your docker is up running)
35+
### Local development environment details
3636

37-
```plain
38-
docker-compose up -d
39-
```
37+
This will run the following components:
4038

41-
This will run the following components:
42-
* Nginx, a web server: http://localhost:8000
43-
* Adminer, a DB front-end: http://localhost:8001
44-
* Mailhog, a dummy mailbox: http://localhost:8025
45-
* A PostgreSQL database
46-
* Django web application
39+
- Nginx, a web server: http://localhost:8000 - view the application or make API calls
40+
- Mailhog, a dummy mailbox: http://localhost:8025
41+
- The Django web application
42+
- Adminer, a DB front-end: http://localhost:8001
43+
- A PostgreSQL database `postgres://babyyoda:mysecretpassword@localhost:5432/codebuddies`
4744

45+
You can access the database through the Adminer front-end or using a local PostgreSQL client
4846

49-
* __Web Server (Nginx)__
50-
You can view the application or make API calls by using the Nginx URL
47+
![screenshot of Adminer](https://i.imgur.com/Dtg5Yel.png =250x)
5148

52-
* __Accessing Database (Adminer)__
53-
You can access the database through the Adminer front-end or using a loca PostgreSQL client with the following command:
49+
5. Create a superuser so that you can log into `http://localhost:8000/admin` by running the following in your terminal:
5450

55-
```plain
56-
postgres://babyyoda:mysecretpassword@localhost:5432/codebuddies
57-
```
51+
```bash
52+
$ docker-compose run --rm app python ./manage.py createsuperuser
53+
```
5854

59-
5. Create a superuser so that you can log into http://localhost:8000/admin by running the following in your terminal:
60-
```plain
61-
docker-compose run --rm app ./manage.py createsuperuser
62-
```
55+
6. You can populate the database with some random test data for development purposes by running
6356

64-
![screenshot of Adminer](https://i.imgur.com/Dtg5Yel.png)
57+
```bash
58+
$ docker-compose run --rm app python ./manage.py init_data
59+
```
6560

66-
To stop the application and remove all containers, run the following
67-
```plain
68-
docker-compose down
69-
```
61+
All user accounts created by this command have the password `codebuddies`.
7062

71-
### Editing the Code
63+
See the `init_data --help` command for more information:
7264

73-
With the local environment running, you can modify the application code in your editor of choice. As you save changes, the application should reload automatically. There should be no need to restart container to see code changes.
65+
```bash
66+
$ docker-compose run --rm app python ./manage.py init_data --help
7467

75-
## **Django Management via Docker**
68+
usage: manage.py init_data [-h] [--clear-db] [--num-users NUM-USERS]
69+
[--num-tags NUM-TAGS]
70+
[--num-resources NUM-RESOURCES] [--version]
71+
[-v {0,1,2,3}] [--settings SETTINGS]
72+
[--pythonpath PYTHONPATH] [--traceback]
73+
[--no-color] [--force-color]
7674

77-
Notes: The following commands are only applicable to MacOS and Linux.
75+
Initialize the DB with some random fake data for testing and development
7876

79-
__Common Commands for Managing Django project__
77+
optional arguments:
78+
--clear-db Clear existing data from the DB before creating test
79+
data
80+
--num-users NUM-USERS
81+
Number of `User` objects to create (default 10)
82+
--num-tags NUM-TAGS Number of `Tag` objects to create (default 10)
83+
--num-resources NUM-RESOURCES
84+
Number of `Resource` objects to create (default 10)
85+
-v {0,1,2,3}, --verbosity {0,1,2,3}
86+
Verbosity level; 0=minimal output, 1=normal output,
87+
2=verbose output, 3=very verbose output
88+
```
8089

81-
Majority of the Django manage.py commands can also be applied through docker. Below are some examples:
90+
[See PR 127]
8291

83-
* Access Python shell (IPython): `docker-compose run --rm manage shell`
84-
* Run test: `docker-compose run --rm manage test`
92+
---
8593

86-
See the full list of commands: `docker-compose run --rm manage help`
94+
To stop the application and remove all containers, run the following:
8795

88-
__Migrating Models__
8996

90-
If any changes are made on the project models, we will need to migrate it to apply the changes. See [Django Migration](https://docs.djangoproject.com/en/3.0/topics/migrations/) for details.
97+
```bash
98+
$ docker-compose down
99+
```
91100

92-
Steps to apply migrations via docker:
93-
1. Make migrations: `docker-compose run --rm manage makemigrations`
94-
2. Apply migrations: `docker-compose run --rm manage migrate`
101+
## Other Tasks
95102

96-
Merge migrations: `docker-compose run --rm manage makemigrations --merge`
103+
### Automated Tests
97104

98-
## **Import Postman Collection**
99-
Postman is a free interactive tool for verifying the APIs of your project in an isolated environment -- think of it as a virtual playground where we can safely experience and edit our API before we deploy it on your web app -- just like virtual envrionments help us isolate our python dependencies. You can download it at [postman.com/downloads](http://postman.com/downloads).
105+
- We use [pytest](https://docs.pytest.org/en/latest/contents.html) with the [pytest-django](https://pytest-django.readthedocs.io/en/latest/) plugin for running tests.
106+
- Please add tests for your code when contributing.
107+
- Run the test suite using `docker-compose run --rm app pytest`
108+
- With test coverage report `docker-compose run --rm app pytest --cov-report=term --cov=.`
100109

101-
We've created a shared Postman collection (a .json file) in the postman folder to help contributors more easily reproduce observed behaviour in our dev API.
110+
### Debugging with Docker Logs
111+
112+
View logs from all containers.
113+
114+
```bash
115+
$ docker-compose logs
116+
```
117+
118+
View logs from a single container (in this case the `app` container).
119+
120+
```bash
121+
$ docker-compose logs app
122+
```
123+
124+
You can use the same structure to view logs for the other containers; `nginx`, `db`, `mailhog`, `adminer`, `app`.
125+
126+
If you would like to tail the logs in the console then you remove the detach flag, `-d`, from the `docker-compose up` command that you use to start the application.
102127

103-
### Setup
128+
### Django Management
104129

105-
1. Downloading Postman
106-
Please ensure the installed version is later than v7.6.0 if you have previously installed the program.
130+
Migrations are Django's way of propogating model changes into the database schema (([doc](https://docs.djangoproject.com/en/3.1/topics/migrations/)).
107131

108-
(Recommendation for Linux users)
109-
[Flatpak](https://flatpak.org/), which can be downloaded from your Liunx distribution (distro) manager, is recommended to manage Postman.
132+
Whenever you made a change to a model file*, you should run `docker-compose run --rm app python ./manage.py makemigrations` and `docker-compose run --rm app python ./manage.py migrate` in order to update the models for the database.
110133

111-
After setting up flatpak, install postman and enter "yes"/"y" for all the questions it will ask. Flatpak is designed to provide the most up-to-date versions of software for most distros, so if you have the option, use Flatpak to guarantee Linux OS compatibility and to keep Postman up-to-date.
134+
A PR reviewer should see the associated migration files in the PR diff when there is a model change.
112135

113136

114-
2. Open Postman, click on File -> Import -> Import the .json file (path: `cb-backend/postman/CodeBuddies.postman_collection.json`)
137+
The following list contains some common Django management commands that you may need to run.
115138

116-
3. Click the settings gear icon on the far top right (next to the eye icon) and click to add a new environment.
139+
- Make Migrations: `docker-compose run --rm app python ./manage.py makemigrations`
140+
- Merge Migrations: `docker-compose run --rm app python ./manage.py makemigrations --merge`
141+
- Run Migrations: `docker-compose run --rm app python ./manage.py migrate`
142+
- Make sure new packages are installed: `docker-compose up -d --build`
117143

118-
4. Name your environment `dev` and create a variable call `api_url`. Give it a value of `https://localhost:8000`, which is the URL of your Django dev environment when it is running.
144+
To see the full list of management commands use `help`.
119145

120-
5. Now, as long as you have the Django app (https://localhost:8000) running, you should be able to make requests like `POST Create User` and `POST Authenticate` by clicking on the blue "Send" button in Postman. Click on this link to see what you should expect: https://imgur.com/hd9VB6k
146+
```plain
147+
docker-compose run --rm app python ./manage.py help
148+
```
121149

122-
POST Create User will create a new user in your localhost:8000 running Django app, and making a request to POST Authenticate will authenticate whether or not that user exists.
150+
*Examples of changes to model files:
123151

124-
![screenshot of Postman environment variable setup](https://i.imgur.com/6Uq9XQp.png)
152+
PK changes
153+
removals
154+
fieldname changes
155+
multiple sets of changes with reversions
156+
datatype changes
125157

126-
## **Docker Management**
158+
You should be double checking their migration files and consolidating, organizing, and deleting excess where necessary.
127159

128-
### Docker Logs
160+
Only the migration files that make the final intended changes should be checked in (e.g. the final field name in its migration, or the final PK change in its migration).
129161

130-
The `-d` from `docker-compose up -d` allows you to detach logs on the console. To tail logs in the console, type in command `docker-compose up` when you start the application
131162

132-
View logs from all containers
163+
### Editing the Code
164+
165+
With the local environment running, you can modify the application code in your editor of choice. As you save changes, the application should reload automatically. There should be no need to restart container to see code changes.
166+
167+
### Postman
168+
169+
<details>
170+
<summary>Importing Postman collection</summary>
171+
<br>
172+
Postman is a free interactive tool for verifying the APIs of your project. You can download it at postman.com/downloads.
173+
174+
Postman is an interactive tool for verifying the APIs of your project in an isolated environment--think of it as a a virtual playground where we can safely experiment and edit our API before we deploy it on our web app--just like virtual environments help us isolate our python dependencies.
175+
176+
We've created a shared Postman collection (a .json file) in the postman folder to help contributors more easily reproduce observed behaviour in our dev API.
177+
178+
To get it set up, please follow these steps:
133179

134-
```plain
135-
docker-compose logs
136-
```
180+
1. Download Postman
137181

138-
View logs from a single container (in this case the `app` container)
182+
Downloading Postman
183+
Please make sure it is at least v7.6.0, if installed, or you are downloading the latest stable version.
184+
Linux,
139185

140-
```plain
141-
docker-compose logs app
142-
```
186+
- Distro package manager:
187+
- use the search feature to find in your package manager
188+
- (RECOMMENDED) Flatpak
189+
- After setting up flatpak it through flatpak using flatpak install postman and enter "yes"/"y" for all the questions it will ask. Flatpak is designed to provide the most up-to-date versions of software for most distros, so if you have the option, use Flatpak to guarantee Linux OS compatibility and to keep Postman up-to-date.
143190

144-
You can use the same structure to view logs for the other containers: `nginx`, `db`, `mailhog`, `adminer`, `app`
191+
2. Once you have Postman open, click on file -> import and import the .json file
192+
3. Click on the settings gear icon on the far top right (next to the eye icon) and click to add a new environment.
193+
4. Name your environment `dev` and create a variable called `api_url`. For both the "Initial Value" and "Current Value," fill in `http://localhost:8000` which is the URL of your Django dev environment when it is running.
194+
5. Now, as long you have the Django app (http://localhost:8000) running, you should be able to make requests like POST Create User and POST Authenticate.
195+
Click on this link to see what you should expect: https://imgur.com/hd9VB6k
145196

146-
### View docker containers / images / volumes
197+
- `POST` Create User will create a new user in your `localhost:8000` running Django app,
198+
- making a request to `POST Authenticate` will authenticate whether or not that user exists.
147199

148-
To view specific items, run the following:
149-
```plain
150-
docker container ls
151-
```
152-
(Replace `container` to `image` or `volume` to view details)
200+
![screenshot of Postman environment variable setup](https://user-images.githubusercontent.com/4512699/88751261-14fa9280-d10c-11ea-80c4-2934c27254ad.png)
153201

202+
5. Now, as long you have the Django app (http://localhost:8000) running, you should be able to make requests like `POST Create User` and `POST Authenticate` by clicking on the blue "Send" button in Postman.
154203

155-
### Removing Everything
204+
</details>
156205

157-
It is _strongly recommended_ to stop the application using `docker-compose down` which stops all the containers and remove all the containers completely. Using this method will leave a copy of the data volume(holding the PostgreSQL data) behind and the images behind.
206+
## Removing Everything
158207

159-
To remove items on volume or image, run the following:
160-
```plain
161-
docker volume prune
162-
```
163-
(Replace `volume` with `image` to do the same on image)
164-
Remove specific volume
165-
```plain
166-
docker volume rm cb-backend_db_data
167-
```
208+
<details>
209+
<summary>To remove all containers</summary>
210+
<br>
211+
To remove all containers run the following:
168212

169-
Note: it is likely that cached copies of your container images will be retained by Docker on your local machine. This is done to speed things up if you require these images in future. To completely remove unused container images and networks, we recommend you follow Docker [pruning guide](https://docs.docker.com/config/pruning/).
213+
```bash
214+
$ docker-compose rm
215+
```
170216

171-
## **Proof-of-concept Goals**
217+
This will leave a copy of the data volume (holding the PostgreSQL data) behind. To remove that you will need to identify and remove the data volume.
172218

173-
| Resource datastore | Resource |
174-
| ------ | ------ |
175-
|- save resource<br>- delete resource<br>- update resource<br>- list resource<br>- search resources |- title<br>- description<br>- type<br>- credit<br>- url<br>- referrer|
219+
```bash
220+
$ docker volume ls
176221

222+
DRIVER VOLUME NAME
223+
local django-concept_db_data
224+
```
177225

178-
The start of a resource bookmarking/archiving service.
226+
Note the name of the data volume, in this case `django-concept_db_data` and delete it.
179227

180-
- Calendar/hangouts
181-
- How easy would it be to make a calendar widget that lets users block out times they're free for hangouts?
228+
```bash
229+
$ docker volume rm django-concept_db_data
230+
```
182231

183-
# Findings
232+
**Note:** it is likely that cached copies of your container images will be retained by Docker on your local machine. This is done to speed things up if you require these images in future. To completely remove unused container images and networks, we recommend you follow Docker [pruning guide](https://docs.docker.com/config/pruning/).
233+
</details>
184234

185-
# Technologies Used
186-
=======
235+
## Getting Help
236+
Ways you can get help if you're stuck or have questions:
187237

188-
Please see [instructions here](https://github.com/codebuddies/django-concept/wiki/Contribution-instructions)
238+
-[x] Create a [new discussion post](https://github.com/codebuddies/backend/discussions) with your question
189239

190-
This project is not deployed yet, but will interact as the API supporting [https://github.com/codebuddies/frontend](https://github.com/codebuddies/frontend)
240+
-[x] Ask in the #codebuddies-meta channel on the CodeBuddies Slack (see: [codebuddies.org/slack](https://codebuddies.org/slack)

0 commit comments

Comments
 (0)