개발자의 크나큰 고충중 하나는 이름 짓기다. 나 또한 변수명을 지을 때도 꽤나 신경을 많이 쓰는 편이다. 이러한 고충은 Git 저장소에서도 이어진다.
어떤 곳에서는 CamelCase를 사용하거나 도메인명을 사용하는 등 GitHub 저장소 이름과 README.md 작성 스타일은 사람들마다 다르다. URL이 되는 저장소명과 저장소 진입시 가장 먼저 보이는 README.md는 가능한 신경을 써야한다고 생각하기에 구글링을 통해 알아본 명명 규칙과 README.md 작성법을 정리해보고자 한다.
내가 읽었던 블로그들 중에서 마음에 들었던 내용을 조합한다면 다음과 같은 조건을 가지게 된다.
당근 마켓을 예시를 든다면 다음과 같은 형태로 레퍼지토리 이름이 만들어진다.
carrot-spring-backend
carrot-react-frontend
GitHub을 사용하는 경우, 다른 사람들이 프로젝트를 이해할 수 있도록 문서를 작성해야한다. 그 중 README 파일은 프로젝트에 대한 자세한 설명을 사용자에게 제공하는 가이드다. README를 잘 작성한 만큼 해당 프로젝트가 다른 많은 프로젝트와 차별화하는데 도움이 된다. 즉, 프로젝트를 접했을 때 가장 먼저 접하는 파일이므로 간단하면서도 상세해야한다.
README를 구성하는 올바른 방법은 없지만 "what, why, how" 에 대한 질문에 답할 수 있어야 한다.
전체 프로젝트를 한 문장으로 설명하고 사람들이 프로젝트의 주요 목표와 목적이 무엇인지 이해하도록 작성해주어야 한다.
프로젝트의 가장 중요한 부분으로 다른 개발자에게 자신의 작업을 보여주기 위해 작성한다. 예를 들어, "애플리케이션이 하는 일, 해당 기술을 사용한 이유, 문제점과 향후 구현하고자 하는 기능 등" 을 작성할 수 있다.
목차는 선택 사항으로, README가 길 경우에 사용자가 필요한 내용을 쉽게 찾을 수 있도록 도움을 주기 위해 사용된다.
프로젝트가 설치가 필요한 소프트웨어나 앱인 경우, 프로젝트를 설치하는데 필요한 단계를 작성할 때 사용한다. (개발 환경을 실행하는 방법에 대한 단계별 설명이 필요하다. 🧐)
사용자가 프로젝트를 사용할 수 있도록 지침과 예제를 제공하는 부분이다. 실행 중인 프로젝트의 예를 보여주는 스크린샷을 포함하여 작성하는 방법도 있다.
팀으로 프로젝트에 참여했다면 공동 작업자에 대한 구성원을 나열하고 GitHub 프로필에 대한 링크도 포함해주는 곳이다. 만약 튜토리얼을 따라 특정 프로젝트를 빌드했을 경우 해당 튜토리얼에 대한 링크를 포함하여 감사를 표시해준다.
README의 마지막 부분으로, 다른 개발자가 프로젝트에서 할 수 있는 것과 할 수 없는 것을 작성하는 곳이다. 라이선스에 대해 모를 경우, 라이선스 선택지를 제공해주는 Choosealicense 사이트를 참고하면 된다.
오픈소스는 제품을 개발하는 과정에 필요한 소스 코드나 설계를 누구나 접근해서 열람할 수 있도록 공개하는 것이다. 하지만 개인적으로 이용이 가능하나 상업적 이용에는 제한이 있을 수 있다. 따라서 우리는 라이선스를 작성해주어야 한다.
# Apache License
아파치 재단에서 자체 소프트웨어에 적용하기 위한 라이선스다. 개인적/상업적 이용, 배포, 수정, 특허 신청이 가능하다.
# MIT License
MIT 학생들을 위해 개발한 라이선스이며 개인 소스에 이 라이선스를 사용하고 있음을 표시만 해주면 된다. 무료로 사용할 오픈소스에서 가장 많이 확인할 수 있는 라이선스다.
# BSD License
버클리 캘리포니아대학에서 개발한 라이선스로 MIT와 동일하게 표시만 지켜주면 된다.
# Beerware
오픈소스 개발자에게 맥주를 사줘야 하는 라이선스다.
배지는 필요하지 않지만 다른 개발자에게 내가 무엇을 하고 있는지 알 수 있도록 시각적으로 보여주는 방법이다. Shield 사이트를 활용하면 손쉽게 배지를 만들 수 있다.
응용 프로그램이나 패키지를 만들고 다른 개발자가 이에 기여하기를 원하는 경우, 기여를 할 수 있는 방법에 대해 알려주는 지침을 추가하는 곳이다. 기여자 서약 사이트와 GitHub 공식 문서를 통해 작성하면 된다.
애플리케이션에 대한 테스트를 작성하고 코드 예제와 실행 방법을 제공하기 위해 작성하는 부분이다.
매번 모든 내용을 작성할 때 마다 신경을 쓰는건 굉장히 시간을 잡아먹고 번거로운 작업이다. 하지만 README 생성기를 이용하면 직접 작성하지 않고도 간편하게 생성할 수 있다.