(developing_for_wagtail)=

# 개발

[Wagtail git 저장소](https://github.com/wagtail/wagtail)의 로컬 복사본을 설정하는 것은 Wagtail 릴리스 패키지를 실행하는 것보다 약간 더 복잡합니다. JavaScript 및 CSS 에셋을 빌드하기 위해 [Node.js](https://nodejs.org/)와 npm이 필요하기 때문입니다. (릴리스 버전을 실행할 때는 컴파일된 에셋이 릴리스 패키지에 포함되어 있으므로 이 과정이 필요하지 않습니다.)

로컬 가상 머신에서 개발하는 것이 편하다면, [docker-wagtail-develop](https://github.com/wagtail/docker-wagtail-develop) 및 [vagrant-wagtail-develop](https://github.com/wagtail/vagrant-wagtail-develop) 설정 스크립트를 사용하는 것이 가장 빠르게 시작할 수 있는 방법입니다. 이 스크립트들은 실행 중인 [Wagtail Bakery 데모 사이트](https://github.com/wagtail/bakerydemo/) 인스턴스를 제공하며, Wagtail 및 bakerydemo 코드베이스는 호스트 머신에서 편집할 수 있도록 공유 폴더로 제공됩니다.

또한 [gitpod-wagtail-develop](https://github.com/wagtail/gitpod-wagtail-develop) 프로젝트를 사용하여 브라우저 기반 IDE에서 작업할 수 있는 클라우드 개발 환경을 설정할 수도 있습니다.

(다른 플랫폼을 위한 빌드 스크립트도 언제나 환영합니다 - 만약 만드셨다면 [Slack 워크스페이스](https://github.com/wagtail/wagtail/wiki/Slack)를 통해 알려주세요!)

모든 구성 요소를 수동으로 설정하고 싶다면 계속 읽어주세요. 이 지침은 pip와 [가상 환경](inv:python#tutorial/venv)을 사용하여 Python 패키지를 관리하는 데 익숙하다고 가정합니다.

## Wagtail 코드베이스 설정하기

올바른 버전의 Node를 설치하는 가장 좋은 방법은 [Fast Node Manager (fnm)](https://github.com/Schniz/fnm)를 사용하는 것입니다. fnm은 프로젝트 루트의\ `.nvmrc`\ 파일에 명시된 버전과 항상 일치시켜 줍니다. 올바른 버전의 Node를 실행하고 있는지 확인하려면 프로젝트 루트에서\ `fnm install`\ 을 실행하세요. 또는 [Node.js](https://nodejs.org/)를 직접 설치할 수도 있습니다. 이 경우 프로젝트 루트의\ `.nvmrc`\ 파일에 선언된 버전을 설치해야 합니다.

아직 설치하지 않았다면 **libjpeg** 와 **zlib** 라이브러리도 설치해야 합니다 - Pillow의 [플랫폼별 설치 지침](https://pillow.readthedocs.io/en/stable/installation/building-from-source.html#external-libraries)을 참조하세요.

[Wagtail 코드베이스](https://github.com/wagtail/wagtail)를 포크하고 포크한 복사본을 클론하세요:

```sh
git clone https://github.com/username/wagtail.git
cd wagtail
```

**선호하는 [virtualenv를 활성화](virtual_environment_creation)한 상태에서,** 포함된 테스트 및 문서 종속성과 함께 개발 모드로 Wagtail 패키지를 설치하세요:

```sh
pip install -e ."[testing,docs]" --config-settings editable-mode=strict -U
```

정적 에셋 빌드를 위한 도구 체인을 설치하세요:

```sh
npm ci
```

에셋을 컴파일하세요:

```sh
npm run build
```

이제 이 가상 환경에서 시작하는 모든 Wagtail 사이트는 이 개발용 Wagtail 인스턴스에 대해 실행됩니다. Wagtail 개발의 기반으로 [Wagtail Bakery 데모 사이트](https://github.com/wagtail/bakerydemo/)를 사용하는 것을 권장합니다. Wagtail 사이트의 설정 단계에는 릴리스 버전의 Wagtail 설치가 포함될 수 있으며, 이 경우 방금 설정한 개발 버전이 재정의될 수 있다는 점을 명심하세요. 이 경우, Wagtail 사이트의 가상 환경에 로컬 Wagtail 개발 인스턴스를 설치하려면 다음을 실행하세요:

```sh
pip install -e path/to/wagtail"[testing, docs]" --config-settings editable-mode=strict -U
```

여기서\ `path/to/wagtail`\ 은 로컬 Wagtail 복사본의 경로입니다.

(development_on_windows)=

## Windows에서 개발하기

Windows에서의 개발에 대한 문서는 일부 미흡한 부분이 있으며 진행 중인 작업으로 간주해야 합니다. 이미 사용 가능한 스크립트인 [docker-wagtail-develop](https://github.com/wagtail/docker-wagtail-develop) 또는 [vagrant-wagtail-develop](https://github.com/wagtail/vagrant-wagtail-develop)를 사용하여 로컬 가상 머신에 설정하는 것을 권장합니다.

Windows에서 Python 및 Node 개발에 자신이 있고 여기서 계속 진행하고 싶다면 몇 가지 유용한 팁이 있습니다.

Windows에서 패키지를 관리하기 위해 [Chocolatey](https://chocolatey.org/install)를 사용하는 것을 권장합니다. Chocolatey가 설치되면\ [`make`](https://community.chocolatey.org/packages/make)\ 유틸리티를 설치하여 일반적인 빌드 및 개발 명령을 실행할 수 있습니다.

우리는 줄 끝(line ending)으로 LF를 사용합니다. 다른 운영 체제의 다른 개발자들과 효과적으로 협업하려면, Git의 자동 CRLF 처리를 사용하도록\ `core.autocrlf`\ 설정을\ `true`\ 로 설정하세요:

```doscon
git config --global core.autocrlf true
```

(testing)=

## 테스트

Wagtail 코드베이스의 루트에서 다음 명령을 실행하여 모든 Python 테스트를 실행하세요:

```sh
python runtests.py
```

### 일부 테스트만 실행하기

이 글을 쓰는 시점에서 Wagtail에는 5000개가 넘는 테스트가 있으며, 이를 실행하는 데는 시간이 걸립니다. Wagtail의 일부에 대한 테스트만 실행하려면\ `runtests.py`\ 또는\ `tox`\ 에 인수로 경로를 전달하면 됩니다:

```sh
# 현재 환경에서 실행
python runtests.py wagtail

# 지정된 Tox 환경에서 실행
tox -e py39-dj32-sqlite-noelasticsearch -- wagtail

# 사용 가능한 Tox 환경 목록 보기
tox -l
```

또한\ `runtests.py`\ 에 인수로 경로를 전달하여 개별 TestCase에 대한 테스트를 실행할 수도 있습니다:

```sh
# 현재 환경에서 실행
python runtests.py wagtail.tests.test_blocks.TestIntegerBlock

# 지정된 Tox 환경에서 실행
tox -e py39-dj32-sqlite-noelasticsearch -- wagtail.tests.test_blocks.TestIntegerBlock
```

### 테스트 앱 모델에 대한 마이그레이션 실행하기

Wagtail 루트에서 다음을 실행하여 테스트 앱에 대한 마이그레이션을 생성할 수 있습니다.

```sh
django-admin makemigrations --settings=wagtail.test.settings
```

### PostgreSQL에 대해 테스트하기

```{note}
이 테스트를 실행하려면 Django의 [데이터베이스 문서](inv:django#ref/databases)에 설명된 대로 PostgreSQL에 필요한 모듈을 설치해야 합니다.
```

기본적으로 Wagtail은 SQLite에 대해 테스트합니다. PostgreSQL을 사용하도록 전환하려면\ `--postgres`\ 인수를 사용하면 됩니다:

```sh
python runtests.py --postgres
```

다른 사용자, 암호, 호스트 또는 포트를 사용해야 하는 경우 각각\ `PGUSER`\ , \`PGPASSWORD\`\ , \`PGHOST\`\ , \`PGPORT\`\ 환경 변수를 사용하세요.

### 다른 데이터베이스에 대해 테스트하기

```{note}
이 테스트를 실행하려면 Django의 [데이터베이스 문서](inv:django#ref/databases) 또는 서드파티 데이터베이스 백엔드 문서에 설명된 대로 지정된 데이터베이스에 필요한 클라이언트 라이브러리와 모듈을 설치해야 합니다.
```

다른 데이터베이스에 대해 테스트해야 하는 경우,\ `DATABASE_ENGINE`\ 환경 변수를 테스트할 Django 데이터베이스 백엔드의 이름으로 설정하세요:

```sh
DATABASE_ENGINE=django.db.backends.mysql python runtests.py
```

이렇게 하면 MySQL에\ `test_wagtail`\ 이라는 새 데이터베이스가 생성되고 이에 대해 테스트가 실행됩니다.

다른 연결 설정을 사용해야 하는 경우, Django의\ [`DATABASES`](inv:django#DATABASES)\ 설정 사전 내의 각 키에 해당하는 다음 환경 변수를 사용하세요:

-   `DATABASE_ENGINE`
-   `DATABASE_NAME`
-   `DATABASE_PASSWORD`
-   `DATABASE_HOST`
    -   MySQL의 경우, TCP 소켓을 사용하여 연결해야 한다면 `localhost` 대신\ `127.0.0.1`\ 이어야 합니다.
-   `DATABASE_PORT`

SQL Server 엔진을 사용하는 경우\ `OPTIONS`\ 내의\ `driver`\ 값에 해당하는\ `DATABASE_DRIVER`\ 를 설정할 수도 있습니다.

### Elasticsearch 테스트하기

`--elasticsearch7`\ 또는\ `--elasticsearch8`\ 인수(테스트하려는 Elasticsearch 버전에 해당)를 전달하여 Elasticsearch에 대해 Wagtail을 테스트할 수 있습니다:

```sh
python runtests.py --elasticsearch8
```

Wagtail은 로컬 Elasticsearch 인스턴스(`http://localhost:9200`)에 연결을 시도하고\ `test_wagtail`\ 인덱스를 사용합니다.

Elasticsearch 인스턴스가 다른 곳에 있는 경우,\ `ELASTICSEARCH_URL`\ 환경 변수를 해당 위치를 가리키도록 설정할 수 있습니다:

```sh
ELASTICSEARCH_URL=https://my-elasticsearch-instance:9200 python runtests.py --elasticsearch8
```

### JavaScript 유닛 테스트

클라이언트 측 비즈니스 로직이나 UI 컴포넌트의 유닛 테스트에는 [Jest](https://jestjs.io/)를 사용합니다. Wagtail 코드베이스의 루트에서 다음 명령을 실행하여 모든 프론트엔드 유닛 테스트를 실행하세요:

```sh
npm run test:unit
```

### 통합 테스트

엔드투엔드 브라우저 테스트 스위트도 [Jest](https://jestjs.io/)와 [Puppeteer](https://pptr.dev/)를 함께 사용합니다. 기존 Node 도구의 설치 크기를 늘리지 않기 위해 별도로 설치하도록 설정했습니다. 테스트를 실행하려면 종속성을 설치하고 별도의 터미널에서 테스트 스위트의 Django 개발 서버를 실행해야 합니다:

```sh
export DJANGO_SETTINGS_MODULE=wagtail.test.settings_ui
# 현재 환경에 로컬 개발용 Wagtail이 유효하게 설치되어 있다고 가정합니다.
./wagtail/test/manage.py migrate
./wagtail/test/manage.py createcachetable
DJANGO_SUPERUSER_EMAIL=admin@example.com DJANGO_SUPERUSER_USERNAME=admin DJANGO_SUPERUSER_PASSWORD=changeme ./wagtail/test/manage.py createsuperuser --noinput
./wagtail/test/manage.py runserver 0:8000
# 별도의 터미널에서:
npm --prefix client/tests/integration install
npm run test:integration
```

통합 테스트는 기본적으로\ `http://127.0.0.1:8000`\ 을 대상으로 합니다.\ `TEST_ORIGIN`\ 환경 변수를 사용하여 다른 포트를 사용하거나 원격 Wagtail 인스턴스를 테스트할 수 있습니다:\ `TEST_ORIGIN=http://127.0.0.1:9000 npm run test:integration`\ .

### 브라우저 및 기기 지원

Wagtail은 다양한 기기와 브라우저에서 사용되도록 만들어졌습니다. 지원되는 브라우저/기기 버전은 다음과 같습니다:

| 브라우저 | 기기/OS | 버전 |
| --- | --- | --- |
| 모바일 Safari | iOS Phone | 최신 2개 버전: 17, 18 |
| 모바일 Safari | iOS Tablet | 최신 2개 버전: 17, 18 |
| Chrome | Android | 최신 2개 버전 |
| Chrome | 데스크톱 | 최신 2개 버전 |
| MS Edge | Windows | 최신 2개 버전 |
| Firefox | 데스크톱 | 최신 버전 |
| Firefox ESR | 데스크톱 | 최신 버전: 128 |
| Safari | macOS | 최신 3개 버전: 16, 17, 18 |

우리는 Wagtail이 이러한 환경에서 작동하는 것을 목표로 합니다. 우리의 개발 표준은 사이트가 다른 브라우저에서도 사용 가능하고 **미래의 브라우저에서도 작동하도록** 보장합니다.

**지원되지 않는 브라우저/기기는 다음과 같습니다:**

| 브라우저 | 기기/OS | 버전 |
| --- | --- | --- |
| 기본 브라우저 | Android | 모두 |
| IE | 데스크톱 | 모두 |
| Safari | Windows | 모두 |

### 접근성 목표

우리는 다양한 보조 기술 사용자들이 Wagtail에 접근할 수 있도록 만들고 싶습니다. 우리가 목표로 하는 구체적인 표준은 [WCAG2.1](https://www.w3.org/TR/WCAG21/), AA 수준입니다. 우리가 테스트하고 궁극적으로 지원하고자 하는 구체적인 보조 기술은 다음과 같습니다:

-   Windows의 Firefox ESR에서 [NVDA](https://www.nvaccess.org/download/)
-   macOS의 Safari에서 [VoiceOver](https://support.apple.com/en-gb/guide/voiceover-guide/welcome/web)
-   [Windows 돋보기](https://support.microsoft.com/en-gb/help/11542/windows-use-magnifier) 및 macOS 확대/축소
-   Windows 음성 인식 및 macOS 받아쓰기
-   모바일 [VoiceOver](https://support.apple.com/en-gb/guide/voiceover-guide/welcome/web) (iOS) 또는 [TalkBack](https://support.google.com/accessibility/android/answer/6283677?hl=en-GB) (Android)
-   Windows [고대비 모드](https://support.microsoft.com/en-us/windows/use-high-contrast-mode-in-windows-10-fedc744c-90ac-69df-aed5-c8a90125e696)

우리는 Wagtail이 이러한 환경에서 작동하는 것을 목표로 합니다. 우리의 개발 표준은 사이트가 다른 보조 기술과도 함께 사용될 수 있도록 보장합니다. 실제로 보조 기술로 테스트하는 것은 전문적인 훈련이 필요한 어려운 작업일 수 있습니다. 다음은 개발 및 코드 리뷰 중에 접근성 문제를 식별하는 데 도움이 되는 도구들입니다:

-   통합 테스트의 일부로 Axe 검사를 실행하는 [@wordpress/jest-puppeteer-axe](https://github.com/WordPress/gutenberg/tree/trunk/packages/jest-puppeteer-axe)
-   특정 페이지에 대한 더 포괄적인 자동화 테스트를 위한 [Axe](https://chrome.google.com/webstore/detail/axe/lhdoppojpmngadmnindnejefpokejbdd) Chrome 확장 프로그램
-   반자동화 테스트 및 수동 감사를 위한 [Accessibility Insights for Web](https://accessibilityinsights.io/docs/en/web/overview) Chrome 확장 프로그램

### 알려진 접근성 문제

Wagtail의 관리 인터페이스는 현재 완전히 접근 가능하지 않습니다. 우리는 지속적인 유지보수와 대규모 개편의 일환으로 문제를 해결하기 위해 적극적으로 노력하고 있습니다. 알려진 문제에 대해 알아보려면 다음을 확인하세요:

-   [CMS admin을 위한 WCAG2.1 AA](https://github.com/wagtail/wagtail/projects/5) 이슈 백로그
-   우리의 [2021년 접근성 감사](https://docs.google.com/spreadsheets/d/1l7tnpEyJiC5BWE_JX0XCkknyrjxYA5T2aee5JgPnmi4/edit)

감사 보고서에는 Wagtail의 어떤 부분이 테스트되었고 어떤 부분이 테스트되지 않았는지, 문제가 WCAG 2.1 준수에 어떤 영향을 미치는지, 그리고 사용자에게 미칠 수 있는 영향 등이 명시되어 있습니다.

## 정적 에셋 컴파일하기

Wagtail 관리자용 JavaScript, CSS, 이미지, 폰트와 같은 모든 정적 에셋은 Webpack에 의해 각 소스로부터 컴파일됩니다. 컴파일된 에셋은 저장소에 커밋되지 않으며, 각 새 릴리스를 패키징하기 전에 컴파일됩니다. 컴파일된 에셋은 풀 리퀘스트의 일부로 제출되어서는 안 됩니다.

에셋을 컴파일하려면 다음을 실행하세요:

```sh
npm run build
```

이 작업은 소스 파일을 변경할 때마다 수행해야 합니다. 소스 파일의 변경 사항을 감시하고 자동으로 에셋을 다시 컴파일하려면 다음을 실행하세요:

```sh
npm start
```

## 패턴 라이브러리 사용하기

Wagtail의 UI 컴포넌트 라이브러리는 [Storybook](https://storybook.js.org/)과 [django-pattern-library](https://github.com/torchbox/django-pattern-library)로 구축되었습니다. 로컬에서 실행하려면,

```sh
export DJANGO_SETTINGS_MODULE=wagtail.test.settings_ui
# 현재 환경에 로컬 개발용 Wagtail이 유효하게 설치되어 있다고 가정합니다.
./wagtail/test/manage.py migrate
./wagtail/test/manage.py createcachetable
./wagtail/test/manage.py runserver 0:8000
# 별도의 터미널에서:
npm run storybook
```

마지막 명령은\ `http://localhost:6006/`\ 에서 Storybook을 시작합니다. 기본적으로 특정 요청을\ `http://localhost:8000`\ 의 Django로 프록시합니다. Django에 다른 포트를 사용하려면\ `TEST_ORIGIN`\ 환경 변수를 사용하세요:\ `TEST_ORIGIN=http://localhost:9000 npm run storybook`\ .

## 문서 컴파일하기

Wagtail 문서는 Sphinx로 빌드됩니다. Sphinx를 설치하고 문서를 컴파일하려면 다음을 실행하세요:

```sh
# wagtail 루트 디렉토리에서 시작:

# 문서 종속성 설치
pip install -e .[docs] --config-settings editable-mode=strict
# 또는 zsh 셸을 사용하는 경우:
#    pip install -e '.[docs]' -U
# 문서 컴파일
cd docs/
make html
```

컴파일된 문서는 이제\ `docs/_build/html`\ 에 있습니다.
웹 브라우저에서 이 디렉토리를 열어 확인하세요.
Python에는 웹 브라우저에서 정적 파일을 매우 쉽게 미리 볼 수 있는 모듈이 함께 제공됩니다.
이 간단한 서버를 시작하려면 다음 명령을 실행하세요:

```sh
# wagtail 루트 디렉토리에서 시작:

cd docs/_build/html/
python -m http.server 8080
```

이제 웹 브라우저에서 <http://localhost:8080/>을 열어 컴파일된 문서를 볼 수 있습니다.

Sphinx는 후속 컴파일 속도를 높이기 위해 빌드된 문서를 캐시합니다.
불행히도 이 캐시는 수정되지 않은 문서 소스 파일에서 발생하는 모든 경고를 숨깁니다.
빌드된 HTML을 지우고 새로 시작하여 문서 빌드 시 발생하는 모든 경고를 보려면 다음을 실행하세요:

```sh
# wagtail 루트 디렉토리에서 시작:

cd docs/
make clean
make html
```

Wagtail은 또한 각 변경 시마다 문서가 자동으로 컴파일되는 방법을 제공합니다.
이를 위해 다음 명령을 실행하여\ `localhost:4000`\ 에서 변경 사항을 자동으로 확인할 수 있습니다:

```sh
# wagtail 루트 디렉토리에서 시작:

cd docs/
make livehtml
```

## 커밋 시 자동으로 린트 및 코드 형식 지정하기

[pre-commit](https://pre-commit.com/)은 모든 커밋과 함께 코드 린팅 및 형식 지정 검사를 자동으로 실행하도록 구성되어 있습니다. pre-commit을 git hook에 설치하려면 다음을 실행하세요:

```sh
pre-commit install
```

이제 pre-commit은 여러분이 만드는 모든 커밋에 대해 실행됩니다.

(developing_using_a_fork)=

## 설치에 포크 사용하기

때로는 포크에서 Wagtail을 설치해야 할 수도 있습니다. 예를 들어, 여러분의 사이트가 현재 리뷰 대기 중인 버그 수정에 의존하고 있는데 새로운 릴리스를 기다릴 여유가 없는 경우입니다.

Wagtail 릴리스 프로세스에는 정적 에셋 빌드 및 번역 업데이트 단계가 포함되어 있어, 요구사항 파일을 메인 저장소의 특정 git 커밋을 가리키도록 업데이트할 수 없습니다.

포크에서 설치하려면, \`build\`\ (`python -m pip install build`)\ 와 정적 에셋 빌드용 도구(`npm install`)\ 를 설치했는지 확인하세요. 그런 다음, Wagtail git 체크아웃의 루트에서 다음을 실행하세요:

```sh
python -m build
```

이렇게 하면\ `dist/`\ 내에\ `.tar.gz`\ 및\ `.whl`\ 패키지가 생성되며, 이를\ `pip`\ 로 설치할 수 있습니다.

원격 배포의 경우, 일반적으로 이를 공개 URL에 업로드하고 프로젝트의 요구사항 파일에서 표준\ `wagtail`\ 라인 대신 해당 URL을 배치하는 것이 가장 편리합니다.