Knowledge Base Help Center
GitLab README 만들기
읽어보기 101
뭐야?
README는 소개하고 그 텍스트 파일 및 프로젝트를 설명합니다. 프로젝트의 내용을 이해하는 데 일반적으로 필요한 정보가 포함되어 있습니다.
왜 만들어야하나요?
프로젝트를 설치하고 사용하는 방법과 공동 작업하는 방법과 관련하여 청중이 가질 수있는 질문에 쉽게 답할 수있는 방법입니다.
누가 만들어야합니까?
특히 다른 사람이 사용하거나 기여하기를 원하는 경우 프로그래밍 프로젝트에 참여하는 모든 사람.
언제 만들어야합니까?
프로젝트를 다른 사람에게 보여 주거나 공개하기 전에 확실히해야합니다. 새 프로젝트에서 만드는 첫 번째 파일 로 만드는 습관을 들이고 싶을 수 있습니다 .
어디에 넣어야하나요?
프로젝트의 최상위 디렉토리. 여기에서 프로젝트를 처음 접하는 사람이 시작됩니다. GitHub , Bitbucket 및 GitLab 과 같은 코드 호스팅 서비스 도 README를 찾고 프로젝트의 파일 및 디렉터리 목록과 함께 표시합니다.
어떻게해야합니까?
README는 모든 텍스트 파일 형식으로 작성할 수 있지만 요즘 사용되는 가장 일반적인 형식은 Markdown 입니다. 가벼운 서식을 추가 할 수 있습니다. 유용한 참조 가이드 와 대화 형 자습서 가있는 여기 에서 이에 대해 자세히 알아볼 수 있습니다 . 표시 될 수있는 다른 형식으로는 일반 텍스트 , reStructuredText ( Python 프로젝트 에서 일반적 ) 및 섬유 .
모든 텍스트 편집기를 사용할 수 있습니다. Markdown을 편집하는 동안 미리 볼 수있는 많은 편집기 (예 : Atom , Emacs , Sublime Text , Vim 및 Visual Studio Code ) 용 플러그인이 있습니다 .
Typora 와 같은 전용 Markdown 편집기 나 StackEdit 또는 Dillinger 와 같은 온라인 편집기를 사용할 수도 있습니다 . 아래의 편집 가능한 템플릿을 사용할 수도 있습니다.
템플릿
| 마크 다운 입력 (편집 가능) | 렌더링 |
| Foobar Foobar is a Python library for dealing with word pluralization. Installation Use the package manager pip to install foobar. pip install foobarUsage import foobar foobar.pluralize('word') # returns 'words' foobar.pluralize('goose') # returns 'geese' foobar.singularize('phenomena') # returns 'phenomenon'Contributing Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests as appropriate. License MIT | Foobar Foobar는 단어 복수화를 처리하기위한 Python 라이브러리입니다. 설치 패키지 관리자 pip 를 사용하여 foobar를 설치하십시오. pip install foobar용법 import foobar기여 Pull 요청을 환영합니다. 주요 변경 사항의 경우 먼저 문제를 열어 변경하고 싶은 사항을 논의하십시오. 테스트를 적절하게 업데이트하십시오. 특허 MIT |
좋은 읽어보기를위한 제안
프로젝트마다 다르므로이 섹션 중 자신에게 적용되는 섹션을 고려하세요. 템플릿에 사용 된 섹션은 대부분의 오픈 소스 프로젝트에 대한 제안입니다. 또한 README는 너무 길고 상세 할 수 있지만 너무 긴 것이 너무 짧은 것보다 낫다는 것을 명심하십시오. README가 너무 길다고 생각되면 정보를 잘라내는 대신 다른 형식의 문서를 활용 하는 것이 좋습니다.
이름
프로젝트에 대한 자명 한 이름을 선택하십시오.
기술
프로젝트가 구체적으로 무엇을 할 수 있는지 사람들에게 알립니다. 컨텍스트를 제공하고 방문자가 잘 모르는 참조 링크를 추가합니다. 기능 목록 또는 배경 하위 섹션도 여기에 추가 할 수 있습니다. 프로젝트에 대한 대안이있는 경우 차별화 요소를 나열하는 것이 좋습니다.
배지
일부 README에서는 프로젝트에 대한 모든 테스트 통과 여부와 같은 메타 데이터를 전달하는 작은 이미지를 볼 수 있습니다. Shields 를 사용 하여 README에 일부를 추가 할 수 있습니다 . 많은 서비스에는 배지 추가 지침도 있습니다.
비주얼
무엇을 만들고 있는지에 따라 스크린 샷이나 동영상을 포함하는 것이 좋습니다 (실제 동영상이 아닌 GIF를 자주 볼 수 있음). ttygif 와 같은 도구 가 도움이 될 수 있지만 더 정교한 방법은 Asciinema 를 확인하십시오 .
설치
특정 생태계 내에서 Yarn , NuGet 또는 Homebrew 사용과 같은 일반적인 설치 방법이있을 수 있습니다. . 그러나 README를 읽는 사람이 초보자이며 더 많은 지침을 원할 가능성을 고려하십시오. 특정 단계를 나열하면 모호함을 제거하고 사람들이 최대한 빨리 프로젝트를 사용하도록 유도 할 수 있습니다. 특정 프로그래밍 언어 버전 또는 운영 체제와 같은 특정 컨텍스트에서만 실행되거나 수동으로 설치해야하는 종속성이있는 경우 요구 사항 하위 섹션 도 추가하십시오 .
용법
예제를 자유롭게 사용하고 가능한 경우 예상 출력을 표시하십시오. README에 합리적으로 포함하기에는 너무 길면 더 복잡한 예제에 대한 링크를 제공하면서 시연 할 수있는 가장 작은 사용 예제를 인라인하는 것이 유용합니다.
지원하다
도움을받을 수있는 곳을 사람들에게 알려주십시오. 이슈 트래커, 채팅방, 이메일 주소 등의 조합이 될 수 있습니다.
로드맵
향후 릴리스에 대한 아이디어가있는 경우 README에 나열하는 것이 좋습니다.
기여
여러분이 기여에 대해 열려 있는지, 그리고 그것들을 받아들이 기위한 여러분의 요구 사항을 설명하십시오.
프로젝트를 변경하려는 사람들에게는 시작하는 방법에 대한 몇 가지 문서가 있으면 도움이됩니다. 실행해야하는 스크립트 나 설정해야하는 환경 변수가있을 수 있습니다. 이 단계를 명시 적으로 만드십시오. 이러한 지침은 미래의 자신에게도 유용 할 수 있습니다.
코드 를 lint 하거나 테스트를 실행 하는 명령을 문서화 할 수도 있습니다 . 이러한 단계는 높은 코드 품질을 보장하고 변경으로 인해 실수로 무언가가 손상 될 가능성을 줄이는 데 도움이됩니다. 테스트 실행 지침이 있으면 브라우저에서 테스트 하기 위해 Selenium 서버를 시작하는 것과 같이 외부 설정이 필요한 경우 특히 유용 합니다.
저자 및 인정
프로젝트에 기여한 사람들에게 감사를 표하십시오.
특허
오픈 소스 프로젝트의 경우 라이선스 방식을 말합니다 .
프로젝트 상태
프로젝트에 필요한 에너지 나 시간이 부족한 경우 README 상단에 개발이 느려지거나 완전히 중단되었다는 메모를 작성하십시오. 누군가가 프로젝트를 포크하거나 자원하여 관리자 또는 소유자로 참여하여 프로젝트를 계속 진행할 수 있습니다. 관리자에게 명시 적으로 요청할 수도 있습니다.
자주하는 질문
표준 README 형식이 있습니까?
여기에있는 모든 제안이 모든 프로젝트에 적합한 것은 아니므로 README에 어떤 정보를 포함해야하는지는 개발자에게 달려 있습니다.
README 작성에 대한 다른 생각은 무엇입니까?
더 많은 리소스 목록은 Awesome README 를 확인하세요 .
README 파일의 이름은 무엇입니까?
README.md(또는 마크 다운이 아닌 파일 형식을 사용하도록 선택한 경우 다른 파일 확장자). 되어 전통적으로 대문자 가 더 눈에 띄는만큼,하지만 당신이 그것을 생각하면 그것은 큰 문제가 아니다 더 나은 소문자를 보인다 .
동의하지 않거나 변경하고 싶거나 다른 피드백이 있으면 어떻게합니까?
주저하지 말고 문제 를 열거 나 요청을 가져 오십시오 . Twitter 에서 나에게 메시지를 보낼 수도 있습니다 .
마음에 드시나요?
Facebook 및 Neuralink (아마도) 와 같은 과학자 와 회사 가 이에 대해 연구하고 있습니다. 아마도 미래에 당신의 생각 및 / 또는 의식의 사본을 프로젝트에 첨부 할 수있을 것입니다. 그동안 README를 만드십시오.
무엇 향후 계획?
특허
프로젝트가 오픈 소스 인 경우 라이선스 를 포함하는 것이 중요 합니다 . 이 웹 사이트 를 사용 하여 하나를 선택할 수 있습니다.
변경 로그
Make a README는 Keep a Changelog에서 영감을 받았습니다 . 변경 로그는 프로젝트를 프로그래밍에 매우 유용하다 또 다른 파일입니다.
더 많은 문서
README는 프로젝트를 문서화하는 중요하지만 기본적인 방법입니다. 모든 프로젝트에는 적어도 README가 있어야하지만, 더 많은 관련 프로젝트는 위키 나 전용 문서 웹 사이트 에서 혜택을 볼 수 있습니다 . GitHub , Bitbucket 및 GitLab은 모두 프로젝트와 함께 위키 유지 관리를 지원하며 다음은 문서 웹 사이트를 생성하는 데 도움이되는 몇 가지 도구 및 서비스입니다.
기여
README에 “기여”섹션이있는 것은 좋은 시작입니다. 또 다른 접근 방식은 지침을 자체 파일 ( CONTRIBUTING.md)로 분리하는 것입니다. GitHub를 사용하고이 파일이있는 경우 이슈를 생성하거나 풀 리퀘스트 를 여는 사람은 누구나 이에 대한 링크 를 받게 됩니다.
이슈 템플릿 과 풀 요청 템플릿을 생성 할 수도 있습니다 . 이러한 파일은 사용자와 공동 작업자에게 적절하게 응답하는 데 필요한 정보를 채울 수있는 템플릿을 제공합니다. 이것은 매우 모호한 문제가 발생하는 것과 같은 상황을 피하는 데 도움이됩니다. GitHub와 GitLab 은 모두 템플릿을 자동으로 사용합니다.