호환성 정책

1.0부터 django-wireview는 여기서 공개라고 적은 것을 마이너·패치 릴리스에서 깨지 않는다. 공개가 아닌 것은 예고 없이 바뀔 수 있다. 1.0 전(0.x)에는 마이너 릴리스도 호환을 깰 수 있다.

무엇이 공개인가#

Python API: wireview의 __all__#

공개 Python API는 최상위 패키지 wireview가 __all__로 내보내는 이름뿐이다(#98).

from wireview import Component, LiveComponent, JS, mount

wireview.core.*, wireview.features.*, wireview.consumer, wireview.repository 같은 하위 모듈은 모두 내부다. 그 안의 이름을 직접 import하면 마이너 릴리스에서 경로가 바뀌어도 알림이 없다. 필요한 이름이 __all__에 없으면 이슈로 요청한다.

telemetry는 모듈 자체가 공개 이름이다(from wireview import telemetry). 시그널을 모아 둔 네임스페이스이고, 그 모듈의 __all__이 공개 범위다.

Component와 LiveComponent는 이름뿐 아니라 멤버도 약속한다. 무엇이 공개인지는 Component API가 정본이다. 밑줄이 없어도 거기 없는 멤버는 내부다.

마이너 릴리스는 Component와 LiveComponent에 멤버를 더할 수 있다. 더한 이름은 프레임워크의 것이 되므로, 사용자 컴포넌트에 같은 이름의 메서드가 있으면 그 메서드는 그날부터 이벤트 핸들러가 아니다(노출 규칙, Component API). 그 이름에 바인딩한 {% on %}은 렌더할 때 오류로 알려 주고, manage.py check는 그런 메서드를 wireview.W018로 미리 알린다. 같은 이름의 필드는 멤버를 가리며 Pydantic이 클래스를 정의할 때 UserWarning("shadows an attribute in parent")을 낸다. 그래서 새 멤버는 항상 CHANGELOG.md에 이름과 함께 적고, 흔히 쓰일 만한 이름이면 그 사실을 따로 적는다. 1.0 직전(rc4 뒤)에 on_upload_complete가 같은 방식으로 프레임워크의 것이 되었다 — 문서가 가르친 그 이름의 콜백이 클라이언트 이벤트로도 열려 있었기 때문이다.

WireviewMeta는 타입 주석용 이름으로만 공개다(wire: WireviewMeta). 생성자와 멤버는 아래 self.wire 행이 정한 넷만 공개다.

tests/test_public_api.py가 이 경계를 지킨다. __all__, 지연 로딩 표, 타입 검사용 import가 서로 같은지 보고, 사용자용 문서(README.md, docs/features/, docs/tutorials/, 앱 개발자용 스킬)와 examples/가 from wireview import ...로만 import하며 그 이름이 모두 공개인지 본다.

통합 지점#

이름을 import하지 않고 경로나 문자열로 가리키는 것도 공개다.

내부 (공개처럼 보이지만 아닌 것)#

와이어 프로토콜#

서버와 브라우저 사이의 메시지 형태는 공개가 아니다. 대신 번들과 서버가 버전이 달라도 페이지가 깨지지 않는다는 것을 약속한다. 규칙은 wire-protocol §7이다.

없애는 절차#

공개 API를 없앨 때는 한 메이저 버전 동안 동작하게 두고 경고를 낸다.

1. 옛 이름은 계속 동작하고, 쓰일 때 wireview.WireviewDeprecationWarning을 낸다. 경고는 새 이름과 제거될 버전을 말한다(wireview/deprecation.py의 warn_deprecated).
2. 다음 메이저 릴리스에서 지운다.
3. 두 단계 모두 CHANGELOG.md에 적는다.

WireviewDeprecationWarning은 DeprecationWarning의 하위 클래스다. 그래서 파이썬의 기본 필터 아래에서는 운영 서버의 로그에 보이지 않는다 — 기본 필터는 __main__에서 난 DeprecationWarning만 보여 준다. 폐기 예정인 것을 쓰는지는 테스트(pytest는 보여 준다)나 python -W default::DeprecationWarning·python -X dev로 띄운 서버에서 확인한다. 테스트에서 경고를 오류로 바꾸려면:

import warnings

from wireview import WireviewDeprecationWarning

warnings.simplefilter("error", WireviewDeprecationWarning)

현재 진행 중인 것:

지원 범위#

Django가 보안 지원하는 Django 버전과, 그 버전들이 지원하는 Python 중 3.12 이상을 지원한다. 지금은 Django 5.2 LTS·6.0·6.1, Python 3.12·3.13·3.14다.

• Django가 한 버전의 지원을 끝내면 그다음 마이너 릴리스에서 그 버전을 뺀다. 메이저를 올리지 않는다 — Django가 이미 끝낸 버전을 붙잡는 것은 사용자를 지키는 일이 아니다.
• 새 Django·Python 버전은 매트릭스를 통과하면 패치 릴리스로 더한다.
• Django에 상한을 두지 않는다(django>=5.2). 그래서 매트릭스를 아직 통과하지 않은 새 Django(예: 7.0)도 설치된다. 그 조합은 위 줄의 패치 릴리스가 나오기 전까지 지원 범위 밖이다. 검증된 조합에 머물려면 프로젝트에서 상한을 직접 건다(django<7).
• 정본은 pyproject.toml(의존성·classifier)과 .github/workflows/ci.yml의 매트릭스다. 같은 격자를 로컬에서 make test-matrix로 돈다(CI는 수동으로만 돈다).
• 의존성의 하한도 약속이다. pyproject.toml이 허용하는 가장 오래된 조합(지금은 Django 5.2, channels 4.2.1, pydantic 2.7.0)을 make test-lowest가 Python 3.12에서 설치해 스위트를 돈다. CI의 test-lowest 잡이 같은 것이다. 하한 조합이 깨지면 하한을 올리고 CHANGELOG.md에 적는다(#132). 반대쪽 끝, 새 설치가 받는 최신 해는 make test-latest다.
• 설치되지 않거나 지원하는 기능(채널 레이어 포함)에서 동작하지 않던 하한을 올리는 것은 패치 릴리스다. 그 하한에 머문 사용자는 그 기능이 동작하는 조합을 갖고 있지 않았다. 지원하는 모든 기능에서 동작하던 하한을 올리는 것은 마이너 릴리스다.
• channels의 하한은 tests/test_nats_layer.py가 지킨다. 그 테스트는 nats-server 바이너리가 없으면 로컬에서는 건너뛰지만 CI(CI 환경 변수)에서는 실패한다. CI의 단위 테스트 잡들은 E2E와 같은 nats 이미지에서 바이너리를 꺼내 쓴다.

채널 레이어#

프로세스가 둘 이상이면 브로커가 있는 레이어가 필요하다. 지원하는 것은 아래 둘이고, 둘 다 E2E 스위트 전체를 돈다(#130).

• InMemory는 단일 프로세스 전용이다. 여러 프로세스에 두면 브로드캐스트가 같은 프로세스의 연결에만 닿고 오류는 나지 않는다. 개발 서버와 단일 프로세스 배포에만 쓴다.
• 검증한 버전은 uv.lock이 고정한 버전이다. CI의 E2E 잡이 레이어마다 한 번씩 그 버전으로 돈다 (make ci-test-e2e LAYER=nats|redis, 브로커는 표의 릴리스 태그 이미지를 서비스 컨테이너로 띄운다). 로컬에서는 make test-e2e(NATS)와 make test-e2e LAYER=redis(REDIS_URL의 redis-server)다.
• channels-nats는 channels 4.2.1 이상에서만 동작한다. 4.2.1에서 생긴 require_valid_channel_name을 부른다. 0.2.1부터는 자신도 channels>=4.2.1을 선언하지만 0.2.0은 channels>=4라고 선언했고 여전히 설치된다. django-wireview의 하한이 channels>=4.2.1인 이유다(#132).
• channels-nats 0.7.0부터는 Python 3.13 이상이 필요하다. 그래서 표의 버전은 Python 3.12에서도 설치되는 0.6.x다. 저장소의 dev 의존성이 channels-nats<0.7로 묶여 있어 uv.lock이 Python 버전에 따라 갈라지지 않는다 — 갈라지면 CI의 E2E 레인(Python 3.12)이 한 버전만 검증한다(#150). 3.13 이상에서 pip가 고르는 0.7 이후 버전은 이 표가 검증한 것이 아니다. 표의 버전을 쓰려면 channels-nats<0.7로 고정한다.
• channels-nats 0.3.0에서 와이어 형식이 바뀌었다(본문 msgpack 고정, 일반 채널의 그룹 구독을 큐 그룹으로). 0.2.x와 0.3.0 이상의 프로세스를 한 NATS에 섞으면 서로의 메시지를 읽지 못하므로 모든 프로세스를 함께 올린다. 같은 릴리스에서 CONFIG의 serializer 키가 없어졌다. 적어 두었다면 지운다(남아 있으면 레이어 생성이 TypeError로 실패한다).
• AUTO_BROADCAST의 필드를 줄이는 설정(senders 매핑)은 1.0.0rc4 이전 프로세스가 남아 있지 않을 때 켠다. 그 프로세스는 필드 일부만 담긴 알림을 받으면 빠진 필드를 기본값으로 채운다. 1.0부터는 받는 쪽이 빠진 필드를 deferred로 둔다(#153)(배포).
• 유실을 세는 방법은 배포 가이드의 관측 절이다.
• uv.lock에서 레이어 패키지를 올리면 두 E2E 레인을 돌리고 이 표의 버전을 같이 고친다. tests/test_supported_versions.py가 표와 uv.lock, CI의 E2E 매트릭스가 같은 레이어를 말하는지, ci.yml이 쓰는 브로커 이미지 태그가 표의 브로커 릴리스와 같은지 본다.