From 38afe0c4d1199937cf2cce1d6d9ab4ed8578acec Mon Sep 17 00:00:00 2001 From: Injoon Hwang Date: Thu, 5 Oct 2023 13:38:34 +0000 Subject: [PATCH 1/2] feat(lint): add conventional pre commit hook --- .pre-commit-config.yaml | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a58d1071..9b207684 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,10 +1,16 @@ repos: - repo: https://github.com/psf/black - rev: 23.7.0 + rev: 23.9.1 hooks: - id: black args: [--safe] + - repo: https://github.com/PyCQA/isort + rev: 5.12.0 + hooks: + - id: isort + args: [--profile=black] + - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.4.0 hooks: @@ -14,12 +20,10 @@ repos: - id: end-of-file-fixer - id: mixed-line-ending args: [--fix=lf] - - id: name-tests-test - args: [--pytest-test-first] - id: trailing-whitespace - - repo: https://github.com/PyCQA/isort - rev: 5.12.0 + - repo: https://github.com/compilerla/conventional-pre-commit + rev: v2.4.0 hooks: - - id: isort - args: [--profile=black] + - id: conventional-pre-commit + stages: [commit-msg] From 10141fa77a4c19a0caeec20f3a7b78a0d10aafbd Mon Sep 17 00:00:00 2001 From: Injoon Hwang Date: Thu, 5 Oct 2023 14:03:35 +0000 Subject: [PATCH 2/2] docs(readme): update README with core contents --- README.md | 232 ++++++++---------------------------------------------- 1 file changed, 34 insertions(+), 198 deletions(-) diff --git a/README.md b/README.md index 0a0c6731..a7acf807 100644 --- a/README.md +++ b/README.md @@ -1,218 +1,54 @@ -# SPARCS NewAra API +# Ara API -

- - Logo - -

-

- Restful API for NewAra, KAIST's official community service -

-

- Release - License - Test -

+Restful API for Ara, KAIST's official community service -## Management Information - -- Issue tracking: Notion -- Credentials: S3 sparcs-credentials -- Communication: Slack - - general: #new-ara - - backend: #new-ara-backend - - fontend: #new-ara-frontend - - github commits: #new-ara-noti - - sentry alerts: #new-ara-sentry - - notion changes: #new-ara-notion - - with OB: #ara -- Contact: +![GitHub Pipenv locked Python version (master)][badge/python-version] +[![Code style: black][badge/black]][repo/black] +[![Imports: isort][badge/isort]][isort] +[![pre-commit][badge/pre-commit]][repo/pre-commit] +[![Conventional Commits][badge/conventional-commits]][conventional-commits] ## Project Setup -### Create & Activate Virtual Environment +Use pipenv to install packages. (e.g., `pipenv install `) ```bash -python3 -m pip install pipenv # It must be Python 3.11 -pipenv shell -``` +pipenv --python 3.11 # Use python 3.11 +pipenv shell # Activate virtual environment +pipenv install --dev # Install packages (`--dev` flag for development) -### Install Requirements - -```bash -pipenv install --dev # `--dev` flag for development +# Run `pre-commit` automatically on `git commit` pre-commit install +pre-commit install --hook-type commit-msg ``` -For macOS, you may need to install `openssl` & `mysqlclient` and set -`LDFLAGS=-L/usr/local/opt/openssl/lib` before installing requirements. Only -tested for macOS Mojave. See [link](https://stackoverflow.com/questions/50940302/installing-mysql-python-causes-command-clang-failed-with-exit-status-1-on-mac). - -### Fill Environment Configuration - -Refer to [.env.example file](https://github.com/sparcs-kaist/new-ara-api/blob/master/.env.example) -and write your own `.env` file with required informations filled-in. For SPARCS -SSO, create a test service or ask SYSOP to deploy production server. - -For the test service in [SPARCS SSO](https://sparcssso.kaist.ac.kr/) for local -settings, fill in as below. - -- **Main URL**: (can be anything) -- **Login Callback URL**: -- **Unregister URL**: - -After this, you should make the information in the `.env` file as environment -variables for local run. (In development or porduction server, we do not use -`.env` file. Rather, we use environment variables in `docker-compose.yml` file.) - -To make the make the information in the `.env` file as environment variables for -local run, you can export each manually, or you can use the below command. Check -the `Makefile`'s [env command](https://github.com/sparcs-kaist/new-ara-api/blob/master/Makefile#L32) -and revise it. The command is written assuming you are using `~/.bashrc`. You -might want to revise it to `~/.bash_profile` or `~/.zshrc` according to your -settings. - -```bash -make env -``` - -### Useful Commands - -Most useful commands are already written in the [Makefile](https://github.com/sparcs-kaist/new-ara-api/blob/master/Makefile). -Refer to the `Makefile` and try to understand and use them. - -### Create and Migrate Database - -```bash -make init -``` - -### Collect static files - -```bash -python manage.py collectstatic -``` - -`collectstatic` command collects all static files required to run installed apps -to selected storage - for this project, static S3 bucket. You should open public -access for the static bucket to get appropriate response. - -### Internationalization (i18n) - -[xgettext](https://man7.org/linux/man-pages/man1/xgettext.1.html) is required in -order to generate translation files. Detailed background on this can be found on -[Django's documentations](https://docs.djangoproject.com/en/3.1/topics/i18n/translation/). -To generate translation files, run: - -```bash -make i18n_generate -``` - -Translation files are generated under `ara/locale/(Locale name)/LC_MESSAGES`. -After writing translations, run the following command to apply the translations. - -```bash -make i18n_compile -``` - -### Create log directory - -```bash -sudo mkdir -p /var/log/newara -sudo chown $(whoami) /var/log/newara -``` - -### Run lightweight server for development +## How to Run ```bash +pipenv shell make run ``` -`0` is abbreviation for `0.0.0.0` which refers to 'listening to every incoming hosts'. -**Do not deploy with runserver command - use WSGI. This command is only for development.** - ---- - -## Deployment with Docker - -### docker-compose.yml - -`docker-compose.yml` file is managed in S3 `sparcs-newara` bucket `docker-compose` -directory. For simple local deployment, refer to [docker-compose.example.yml file](https://github.com/sparcs-kaist/new-ara-api/blob/master/docker-compose.example.yml) -and fill in the information needed. - -For [development server](https://newara.dev.sparcs.org/), two docker containsers -are up with the docker-compose file. Using AWS RDS for mysql, elastiCache for redis. - -- api container (used gunicorn for serving. celery-beat also here.) -- celery-worker container - -### docker image - -For managing docker images, we are using AWS ECR, `newara` repository. - -- Using tag `newara:dev` for development server. - -### other docker related files - -- **Dockerfile**: We use virtual environment also inside the docker container. -- **.docker/run.sh**: api container's entrypoint. -- **.docker/run-celery.sh**: celery worker container's entrypoint. -- **.docker/supervisor-app.conf** -- **.docker/supervisor-celery-worker.conf** - -## Project Stack - -### Interpreter - -- `Python 3.11` -- `Pipenv` is used as package manager - - When adding libraries to the virtual environment, you should not use `pip`. - Rather, use `pipenv` command. Refer to [this link](https://pipenv.pypa.io/en/latest/commands/) - for pipenv commands. - -### Framework - -- `Django 4.2` -- `djangorestframework 3.14` - -### Database - -- MySQL 8.0 -- `mysqlclient 2.2` - -Works with MySQL for Linux & macOS, not tested in Windows. Timezone is -automatically adjusted. It is strongly recommended to set default charset of -database or MySQL server to `utf8mb4`. - -### Storage - -- AWS S3 -- `django-s3-storage 0.14` - -Two buckets are used - one for storing static files, one for media files that -users upload. Go to django-s3-storage documentation for required permissions. - -### Authentication - -- SPARCS SSO v2 API -- `djangorestframework SessionAuthentication` - -### API Documentation +## URLs -- `drf-spectacular 0.26` +- Base URL: `/api` +- Admin page: `/api/admin/` +- API documentations: + - `/api/schema/swagger/` + - `/api/schema/redoc/` ---- +## How to Contribute -## Contributors +1. Follow [Conventional Commits][conventional-commits] for writing commit messages. +2. Use type hints strictly. (Check [PEP 484][pep-484].) -See [contributors](https://github.com/sparcs-kaist/new-ara-api/graphs/contributors). +[badge/python-version]: https://img.shields.io/github/pipenv/locked/python-version/sparcs-kaist/new-ara-api/master +[badge/black]: https://img.shields.io/badge/code%20style-black-000000 +[badge/isort]: https://img.shields.io/badge/%20imports-isort-%231674b1?labelColor=ef8336 +[badge/pre-commit]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit +[badge/conventional-commits]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white +[isort]: https://pycqa.github.io/isort +[conventional-commits]: https://conventionalcommits.org +[pep-484]: https://peps.python.org/pep-0484/ +[repo/black]: https://github.com/psf/black +[repo/pre-commit]: https://github.com/pre-commit/pre-commit