안정성
Hwaro는 1.0부터 유의적 버전을 따릅니다. 어떤 1.x 릴리스로 빌드되는 사이트는 이후의 모든 1.x 릴리스에서도 같은 방식으로 빌드됩니다. 예외는 이 페이지에 적힌 것뿐이며, 이 약속을 깨는 변경은 2.0으로 미룹니다.
1.x가 유지하는 것
사이트와 스크립트가 기대는 부분입니다. 1.x 릴리스는 여기에 항목을 추가할 수는 있지만, 없애거나 의미를 바꾸지 않습니다.
| 영역 | 범위 |
|---|---|
config.toml |
문서화된 모든 키의 이름, 타입, 의미, 기본값 |
| 콘텐츠 | 문서화된 front matter 키, 문서화된 Markdown 문법과 확장, 숏코드 호출 문법 |
| 템플릿 | 문서화된 변수, 필터, 함수, 테스트와 이스케이프 규칙 |
| 출력 | 모든 페이지, 섹션, taxonomy 페이지, alias, 피드의 URL, 생성 파일(sitemap.xml, 피드, search.json, robots.txt, llms.txt)의 이름과 위치, 헤딩 id |
| 명령줄 | 명령과 플래그, 종료 코드와 오류 코드, --json 출력의 필드, 기계가 읽도록 문서화된 줄(hwaro serve: ready url=…) |
| GitHub Action | 입력 항목과 각 항목의 동작 |
새 키, 플래그, 필터, --json 필드는 어느 마이너 릴리스에서든 추가될 수 있습니다. JSON 출력을 읽는 코드는 모르는 필드를 무시해야 합니다.
어느 릴리스에서든 바뀔 수 있는 것
- 잘못된 출력. 버그 수정은 그 버그가 만들던 결과를 바꿉니다. 페이지가 잘못 렌더링되고 있었다면 패치 릴리스에서 다르게 렌더링될 수 있습니다. 출력이 달라지는 수정은 릴리스 노트에 모두 적습니다.
- 사람이 읽는 텍스트. 로그, 경고, 오류 메시지의 문구와 배치, 터미널 출력의 모양입니다. 메시지가 아니라
--json출력과 종료 코드를 읽으세요. 경고가 새로 추가될 수도 있습니다. hwaro init이 만드는 것. 스캐폴드의 템플릿, 스타일, 예시 콘텐츠는 계속 개선됩니다. 이미 만들어진 사이트는 건드리지 않습니다.- 내부 파일.
.hwaro/아래의 모든 것(빌드 캐시,hwaro serve출력)입니다. 언제든 지워도 되고 다시 만들어집니다. - 문서화된 범위 밖의 렌더링 세부 사항. 구문 강조된 코드의 정확한 마크업, 생성된 Open Graph 이미지의 픽셀, 생성된 HTML의 공백입니다.
- 성능. 빌드 시간과 메모리 사용량은 약속에 포함되지 않습니다. 다만 느려지는 것은 버그로 다룹니다.
- 문서화되지 않은 동작. 이 문서에 없는 동작에는 기대지 마세요. 문서화가 필요하면 이슈를 열어 주세요.
- 소스 빌드. 최소 Crystal 버전은 마이너 릴리스에서 올라갈 수 있습니다. Hwaro의 소스는 라이브러리가 아니므로 Crystal 클래스와 모듈에는 안정적인 API가 없습니다.
보안 수정은 다른 방법이 없을 때 패치 릴리스에서 동작을 바꿀 수 있습니다. 그런 경우 릴리스 노트에 밝힙니다.
지원 중단
문서화된 기능을 다음 메이저 버전에서 없애기 전에, 1.x 릴리스에서 먼저 지원 중단으로 표시합니다. 빌드가 대체 방법을 알려 주는 경고를 출력하고, hwaro doctor가 보고하며, 문서에 무엇을 대신 써야 하는지 적습니다. 그 기능은 1.x가 끝날 때까지 계속 동작합니다.
새 메이저 버전이 더 이상 읽지 않는 설정 키는 조용히 무시되지 않습니다. 1.0이 [plugins]에 대해 하는 것처럼, 빌드가 그 키를 짚어 경고합니다.
프리릴리스
1.1.0-rc.1처럼 접미사가 붙은 버전은 테스트용으로 내는 릴리스 후보입니다. 정식 릴리스 전까지 바뀔 수 있으며, Homebrew, AUR, Chocolatey, snap stable 채널, latest 컨테이너 태그로는 배포되지 않습니다. GitHub 릴리스 페이지, 같은 이름의 컨테이너 태그, snap candidate 채널에서 설치할 수 있습니다.
내 사이트가 따라갈 릴리스 고르기
| 이렇게 쓰면 | 받는 것 |
|---|---|
hahwul/hwaro@v1, ghcr.io/hahwul/hwaro:1 |
모든 1.x 릴리스. hwaro tool platform이 생성하는 값입니다 |
hahwul/hwaro@v1.2.3, ghcr.io/hahwul/hwaro:1.2.3 |
직접 바꾸기 전까지 그 릴리스 |
ghcr.io/hahwul/hwaro:1.2 |
1.2의 패치 릴리스 |
ghcr.io/hahwul/hwaro:latest |
다음 메이저 버전을 포함한 최신 릴리스 |
hahwul/hwaro@main, ghcr.io/hahwul/hwaro:main |
개발 브랜치. 이 페이지의 약속이 적용되지 않습니다 |
Homebrew, AUR, Chocolatey, snap은 최신 릴리스를 설치합니다. 이 경로로 설치하면서 사이트를 한 버전에 묶어 두려면, 빌드에 쓰는 버전을 CI 설정에 적어 두세요. 고정한 액션이나 이미지는 매번 같은 방식으로 빌드합니다.