26P by xguru 4달전 | favorite | 댓글 1개

- 오픈소스 참여를 쉽게 하기 위해 프로젝트의 아키텍처를 설명하는 파일을 Repo에 추가하자는 글
- 프로젝트에 가끔 기여하는 사람과 핵심 개발자의 가장 큰 차이점은 프로젝트의 아키텍처에 대한 이해도
- 구조에 익숙하지 않으면 패치를 작성하는 시간도 2배이상 걸리지만, 어디를 고쳐야 하는지 위치를 파악하는데에는 10배 이상 많은 시간이 듬
- 고수준 아키텍처를 설명하는 ARCHITECTURE.md 같은 파일을 작성
ㅤ→ 짧게 작성해서 누구나 읽을수 있게, 잘 변경되지 않는 부분들만 정리
ㅤ→ 코드와 동기화 하려고 하지 말고, 매년 2번정도 다시 보기

내용 작성법
ㅤ- 해결하려고 하는 문제에 대한 조감도(Bird's eye view)로 시작
ㅤ- 조금 더 자세한 코드맵 : "X를 하는 것은 어디에 있나요?"
ㅤ- 대략적인 모듈과 이들의 관계를 설명 : 각 모듈이 하는 일은 다른 문서로 연결
ㅤ- 중요한 파일,모듈,타입 들의 이름을 적을것
ㅤㅤ→ 읽는 사람이 이름으로 검색해볼 수 있게 하고, 직접 링크는 하지말 것(연결이 깨질수 있으니)
ㅤ- 레이어와 시스템간의 경계를 명시

* 좋은 예제
- Rust Analyzer 의 Architecture.md - https://github.com/rust-analyzer/rust-analyzer/…
- Caddy Architecture : https://caddyserver.com/docs/architecture

xguru 4달전  [-]

그리고 메인 README.md 에 가능하면 프로젝트의 각 폴더에 대한 설명을 넣어달라는 의견도 좋네요
- https://news.ycombinator.com/item?id=26050082
예제 : https://github.com/diem/diem/…
가능하면 각 폴더에 설명을 넣고, 깃헙이 폴더에 README가 있으면 그 내용을 상위에서 보여주면 좋긴 하겠어요

관련해서 Architecture Decision Records 도 참고하세요
- ADR을 써야 하는 이유 https://news.hada.io/topic?id=2665