Software Release Practice HOWTO Eric S. Raymond 1.0, 21 November 1998 임종호 1999년 5월 8일 beta-2 이 문서는 리눅스 오픈-소스 프로젝트를 위한 바람직한 공개 발표의 관례에 대해 설명한다. 이러한 관례를 따른다면 당신의 코드를 사용하는 사용자와 당신의 코드를 이해하거나 개선하기 위해 도움을 주고 싶어하는 다른 개발자들을 가능한 쉽게 도와줄 수 있다. 이 문서를 초보 개발자는 반드시 읽어야 하며 숙련된 개발자 또한 새로운 프로젝트를 발표하려고 할 때 다시 한번 숙지해야 한다. 바람직한 표준의 관례를 반영하기 위해 이 문서는 정기적으로 개정될 것이다. ______________________________________________________________________ 목차 1. 소개 1.1 왜 이 문서인가? 1.2 이 문서의 새 버전 2. 바람직한 프로젝트 이름과 압축 파일 이름을 짓는 관례 2.1 GNU-스타일의 이름 사용. 접두사-major번호.minor번호.patch번호 2.2 입력하기 쉽고 고유한 이름의 접두사를 고르는데 신중하라 3. 바람직한 개발의 관례 3.1 ANSI C 나 이식가능한 스크립 언어로 작성하라 3.2 C가 이식가능하도록 관례를 따라라 3.3 autoconf/automake/autoheader 를 사용하라 3.4 공개 발표 전에 코드가 온전한지 검사하라 4. 바람직한 배포본 제작의 관례 4.1 tar 파일이 항상 새로운 한 개의 디렉토리에 풀리도록 만들어라 4.2 README를 포함시켜라 4.3 일반적인 파일 이름을 짓는 관례를 존중하고 따라라 5. 바람직하게 알리는 방법에 대한 관례 5.1 c.o.l.a 에 알려라 5.2 주제와 관련된 뉴스그룹에 알려라 5.3 웹사이트를 가져라 5.4 프로젝트 메일링 리스트를 운영하라 5.5 주요한 보관소(major archives)에 공개(release)하라 5.6 RPM을 제공하라 ______________________________________________________________________ 1. 소개 1.1. 왜 이 문서인가? 오픈-소스 코드를 운영하고 사용하며 발전시키기 위해 협력하는 사람을 돕기 위한 바람직한 관례가 있다. 이 관례들 중에 어떤 것은 유닉스 쪽의 관례이거나 리눅스가 나오기 전의 관례들이며 다른 것들은 최근에 새로운 툴의 개발이나 웹(WWW)과 같은 기술의 발전을 통해 생겨난 것들이다. 이 문서는 당신이 바람직한 관례를 배우는 것을 돕는다. 중요한 단락에는 점검 항목이 포함되어 있으며 이것은 당신의 배포본을 위한 사전 점검 (pre-flight checklist for your distribution)이다. 1.2. 이 문서의 새 버전 이 문서는 매월 comp.os.linux.answers 뉴스그룹에 게시될 것이며 sunsite.unc.edu 에 있는 pub/Linux/docs/HOWTO를 포함한 많은 리눅스 FTP 사이트에서 구할 수 있을 것이다. 또, 웹을 통해서 마지막 버전의 하우투를 볼 수 있다. 이 하우투에 대한 어떠한 질문이나 비평도 꺼립김 없이 Eric S. Raymond esr@snark.thyrsus.com 에게 보내주기 바란다. 2. 바람직한 프로젝트 이름과 압축 파일 이름을 짓는 관례 Sunsite와 PSA, CPAN 과 같은 보관소를 유지하는 사람의 작업량이 증가하면서 부분적으로나 전적으로(완전히 사람에 의해서가 아니라) 프로그램에 의한 작업이 증가하는 추세이다. 이러한 상황에서는 파일 분류하는 작업을 하는 컴퓨터 프로그램이 해석하고 이해할 수 있는 규칙적인 형태에 알맞은 프로젝트와 압축 파일의 이름이 중요하게 되었다. 2.1. GNU-스타일의 이름 사용. 접두사-major번호.minor번호.patch번호 당신의 압축 파일이 소문자 알파벳과 숫자로 된 접두사 그 다음 이음선(dash) 그리고 버전 번호, 확장자(extension)와 다른 접미사로 되어 있는 GNU식의 이름을 가지고 있다면 모든 이에게 도움이 될 것이다. version 1, release 2, level 3 인 `foobar'라는 프로젝트를 가지고 있다고 가정해보자. 만약 그것이 하나의 압축 파일의 한부분(아마 소스겠죠)이라면 압축 파일의 이름은 다음과 같을 것이다. foobar-1.2.3.tar.gz 소스 압축 파일 foobar.lsm LSM 파일 (asuming you're submitting to Sunsite). 제발 다음과 같이 사용하지 마라: foobar123.tar.gz 많은 프로그램에게 `foobar123'이라고 불리는 버전 번호가 없는 프로젝트의 압축 파일처럼 보일 것이다. foobar1.2.3.tar.gz 많은 프로그램에게 `foobar1'이라고 불리는 버전 2.3 인 프로젝트의 압축 파일처럼 보일 것이다. foobar-v1.2.3.tar.gz 많은 프로그램이 프로젝트 이름을 `foobar-v1'이라고 생각할 것이다. foo_bar-1.2.3.tar.gz 밑줄(underscore)은 말하고, 입력하고, 기억하기 힘들다. FooBar-1.2.3.tar.gz 당신이 바보(marketing weenie)가 아닌 한 이것 또한 말하고, 입력하고, 기억하기 힘들다. 소스와 바이너리 또는 다른 종류의 바이너리를 구분하거나 파일 이름에 어떤 종류의 제작 옵션을 표현하려면 제발 버전 번호 뒤에 오는 파일 확장자(extension)로 설명해라. 그것은 다음과 같이 한다: foobar-1.2.3.src.tar.gz 소스 foobar-1.2.3.bin.tar.gz 종류를 알 수 없는 바이너리 foobar-1.2.3.bin.ELF.tar.gz ELF 바이너리 foobar-1.2.3.bin.ELF.static.tar.gz ELF 정적 링크된 바이너리 foobar-1.2.3.bin.SPARC.tar.gz SPARC 바이너리 제발 `foobar-ELF-1.2.3.tar.gz'와 같이 사용하지 마라. 왜냐하면 프로그램은 접두사에 삽입된 종류를 나타내는 부분(`-ELF'와 같은)을 이해하기 못하기 때문이다. 일반적으로 바람직한 이름의 형태는 다음과 같은 순서로 되어 있다: 1. 프로젝트 접두사 2. 이음선(dash) 3. 버전 번호 4. 마침표(dot) 5. "src" 또는 "bin" (선택사항) 6. 마침표(dot) 또는 이음선(dash) (마침표를 선호함) 7. 바이너리 종류와 옵션들 (선택사항) 8. 압축 확장자 2.2. 입력하기 쉽고 고유한 이름의 접두사를 고르는데 신중하라 접두사는 모든 프로젝트 파일들에게 공유되어야 하고 읽고 입력하고 기억 하기 쉬워야 한다. 그러므로 밑줄(underscore)은 사용하지 마라. 그리고 아주 특별한 이유가 없다면 대문자로 시작하거나 가운데에 대문자를 사용하지마라. -- 이러한 것들은 눈으로 자연스럽게 읽는 것을 방해하고, 바보가 영리해 보이려는 것처럼 보인다. 접두사가 고유한 것이 아니라면 그것과 같은 이름의 접두사를 가진 프로젝트를 운영하는 사람들을 혼란스럽게 만들 것이다. 그래서 맨 처음 발표하기 전에 이름이 중복되는지 확인해 보라. 확인하기 좋은 곳은 index file of Sunsite 이다. 3. 바람직한 개발의 관례 이에 관한 내용들 중 대부분은 리눅스뿐만 아니라 다른 유닉스에서도 이식가능하도록 프로그램을 작성하는 것과 관련이 있다. 다른 유닉스에 이식가능하게 하는 것은 단지 전문적이고 해커의 고상한 가치의 형태가 아니라, 리눅스 스스로 미래의 변화에 대비하는 것에 가치가 있다. 마지막으로, 다른 사람이 당신의 코드를 리눅스 시스템이 아닌 곳에서 사용하려고 한다면, 이식성은 당신이 받을 성가시고 난처한 메일들을 최소한으로 줄일 수 있을 것이다. 3.1. ANSI C 나 이식가능한 스크립 언어로 작성하라 이식성과 안전성을 위해 ANSI C 나 이식가능한 스크립 언어로 작성해야 한다. 왜냐하면 다른 플랫폼에서의 실행을 위해서이다. 스크립 언어로 적당한 것은 Python, Perl, Tcl, 그리고 Emacs Lisp등이다. 간단한 옛날 shell 은 적당하지 않다. 구별하기 힘든 특이한 표현법과 shell aliases와 같은 사용자 설정의 혼란에 영향을 받는 shell 환경 때문에 실행에 많은 어려움이 있다. 자바는 이식가능한 언어라고 믿어져지지만 리눅스에서의 실행은 아직까지 서툴고 부족하다. 자바의 성장으로 날로 인기가 높아지지만 자바는 여전히 힘든 선택이다. 3.2. C가 이식가능하도록 관례를 따라라 만약 C로 프로그램을 작성한다면 완전한 ANSI 규정(다른 모듈과의 불일치를 알 수 있도록 도와주는 함수 프로타입을 포함한)을 따른 것을 사용해도 괜찮다. 구식의 K&R 컴파일러가 고전적이다. 그 반면, GCC-specific 규정(`-pipe' 옵션과 같은)또는 nested 함수가 이식가능할 것이라고 추측하지마라. 이것들은 갑자기 나타나서 리눅스 시스템, GCC 시스템이 아닌 곳에 옮기려는 사람이 당신을 괴롭히게 만들 것이다. 3.3. autoconf/automake/autoheader 를 사용하라 C를 사용해서 프로그램을 작성했다면 다른 곳에 이식할 수 있도록 조정하고 시스템 설정에 적응하고 또 makefile을 고치기 위해서 autoconf/automake/ autoheader을 사용해라. 요즘 소스를 프로그램을 사용하고(build) 싶어하는 사람들은 "configure; make"라고 치면 깨끗하게 프로그램이 만들어지기를 바란다 -- 그리고 그렇게 해야 한다. 3.4. 공개 발표 전에 코드가 온전한지 검사하라 C로 프로그램을 작성하였다면 `-Wall' 옵션을 사용하여 테스트-컴파일러를 해보고 공개하기 전에 최소한 한번이라도 오류를 제거해야 한다. 이렇게 하면 많은 엄청난 오류들을 발견할 수 있을 것이다. 철저하게 `-pedantic' 옵션을 사용해 컴파일러 하는 것도 좋은 방법이다. Perl을 사용하였다면 공개 전에 perl -c, perl -w, 그리고 perl -T를 사용해서 코드를 검사해야 한다. (Perl에 관한 문서를 참고하라) 4. 바람직한 배포본 제작의 관례 이 지침들은 다른 이들이 당신의 배포본을 다운로드 받고, 검색하고, 압축을 풀 때에 당신의 배포본이 어떻게 보여져야 하는지에 대해 설명한다. 4.1. tar 파일이 항상 새로운 한 개의 디렉토리에 풀리도록 만들어라 초보 개발자들이 하는 가장 성가신 실수 중의 하나가 tar 파일을 배포본이 있는 현재의 디렉토리에 압축이 풀리도록 만드는 것이다. 이것은 현재 디렉토리에 이미 존재하는 파일을 덮어쓸 위험이 있다. 이런 실수를 절대로 하지마라! 그 대신, 프로젝트의 이름을 따서 만든 하나의 공통 디렉토리를 소유하는 압축 파일을 만들어 최상위 디렉토리의 바로 아래 디렉토리에 압축이 풀리도록 만들어라. 여기 makefile 트릭(trick)이 있다. `foobar'이라는 배포본의 디렉토리를 가지고 있으며 SRC가 배포본의 파일 리스트를 포함하고 있다고 가정하면 다음과 같이 하면 된다. 이렇게 하기 위해서는 GNU tar 1.13이 필요하다. VERS=1.0 foobar-$(VERS).tar.gz: tar --name-prefix='foobar-$(VERS)/' -czf foobar-$(VERS).tar.gz $(SRC) 만약 오래된 tar 프로그램을 가지고 있다면 이렇게 하면 된다: foobar-$(VERS).tar.gz: @ls $(SRC) | sed s:^:foobar-$(VERS)/: >MANIFEST @(cd ..; ln -s foobar foobar-$(VERS)) (cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz `cat foobar/MANIFEST`) @(cd ..; rm foobar-$(VERS)) 4.2. README를 포함시켜라 README 또는 READ.ME 파일을 포함시키면 그것은 소스 배포본의 지침서가 될 것이다. 오랜 관례에 따라 이것은 소스의 압축을 풀은 용감한 탐험가가 가장 먼저 읽어야 하는 파일이다. README 파일에 포함되어야 할 바람직한 것들: o 프로젝트의 간단한 설명. o 프로젝트 웹사이트의 주소(만약 가지고 있다면). o 개발자의 제작 환경과 잠재하고 있는 문제점. o 중요한 파일에 대한 설명과 하위 디렉토리. o 제작/설치에 관한 설명이나 그러한 내용을 포함한 파일의 이름 (보통 INSTALL). o 프로젝트를 꾸려 나가는 사람/지원해 주는 사람의 리스트나 그러한 내용을 포함한 파일의 이름(보통 CREDITS). o 최근 프로젝트의 소식이나 그러한 내용을 포함한 파일의 이름 (보통 NEWS). 4.3. 일반적인 파일 이름을 짓는 관례를 존중하고 따라라 README 파일을 보기 전에도 당신의 용감한 탐험가(사용자)는 배포본의 최상위 디렉토리에 있는 파일들을 훑어볼 것이다. 파일의 이름은 그것 자체로 정보를 포함하고 있다. 확실한 일반적 이름 짓는 방법의 관례를 따름으로서 탐험가에게 다음에 무엇을 보아야 할지 실마리를 제공해 줄 수 있다. 여기 몇 개의 일반적인 최상위 파일 이름과 그것들이 의미하는 것이 있다. 모든 배포본이 다음 모두를 필요로 하진 않는다. README 또는 READ.ME 가장 먼저 읽어야 할 지침 파일 INSTALL 설정, 제작(build) 그리고 설치에 관한 정보 CREDITS 프로젝트를 지원해 주는 사람의 리스트 NEWS 최근 프로젝트 소식 HISTORY 프로젝트 변천 과정 COPYING 프로젝트 라이센서 (GNU 관습) LICENSE 프로젝트 라이센서 MANIFEST 배포본의 파일 리스트 FAQ 프로젝트에 관한 `질문과 대답'의 텍스트 형식의 파일 TAGS Emacs나 vi의 사용으로 생긴 파일 사람이 읽을 수 있는 모든 패키지에 관한 정보를 포함한 파일의 이름은 모두 대문자를 사용한다는 것을 기억해 주기 바란다. 5. 바람직하게 알리는 방법에 대한 관례 당신의 소프트웨어가 존재 한다는 것을 당신만 알고 다른 누구도 알지 못 한다면 세상에 좋은 일을 하지 못할 것이다. 인터넷상의 프로젝트의 존재를 알리므로서 초보사용자들과 공동개발자들의 도움을 받을 수 있다. 여기 그렇게 하는 일반적인 방법이 있다. 5.1. c.o.l.a 에 알려라 새로운 공개(releases)를 comp.os.linux.announce 에 알려라. 그리고 많은 사람들이 알 수 있게 Freshmeat 과 같은 웹기반의 what's-new 사이트에도 퍼트려라. 5.2. 주제와 관련된 뉴스그룹에 알려라 당신의 프로그램과 직접적으로 관련된 주제의 USENET 그룹을 찾아서 그곳에 알려라. 코드의 기능가 직접 관련된 곳에만 게시하고 아무 곳에나 게시하지마라. 예를 들어 만약 IMAP servers 에 관련된 프로그램을 Perl을 이용해서 작성했다면, comp.mail.imap에 확실히 게시해야 하겠지만, 새로운 Perl 기술의 교육적인 예가 아니라면 comp.lang.perl에 게시하면 안 될 것이다. 당신이 알릴 때에는 반드시 프로젝트 웹사이트의 주소를 함께 알려야 한다. 5.3. 웹사이트를 가져라 당신의 프로젝트 주위에 많은 사용자들과 개발자들의 집단을 만들고 싶다면 웹사이트가 필요할 것이다. 웹사이트는 일반적인 다음과 같은 것을 포함하고 있어야 한다: o 프로젝트의 개관 (그것이 존재하는 이유, 이용해야 하는 사람 등). o 프로젝트 소스를 다운로드받을 수 있는 링크. o 프로젝트 메일링 리스트에 참여하는 방법. o FAQ (빈번하게 접하는 질문) 리스트. o 프로젝트 문서의 HTML 버전. o 관련이 있거나 경쟁 관계에 있는 프로젝트의 링크. 어떤 프로젝트 사이트는 아무나 마스터(master) 소스에 접근할 수 있는 주소를 가지고 있다. 5.4. 프로젝트 메일링 리스트를 운영하라 프로젝트를 돕는 여러 사람들이 정보를 교환하고 패치를 교환하기 위한 사적인 개발 리스트를 가지는 것은 일반적인 관례이다. 또 프로젝트의 진행 상황을 궁급해 하는 사람들을 위한 공개 리스트를 가지는 것도 좋을 것이다. 5.5. 주요한 보관소(major archives)에 공개(release)하라 지난 몇 년 동안 Sunsite archive 는 리눅스 소프트웨어의 가장 중요한 교환 장소가 되었다. 다른 중요한 곳들의 주소이다: o the Python Software Activity site (Python으로 작성된 프로그램을 위한). o the CPAN , the Comprehensive Perl Archive Network, (Perl로 작성된 프로그램을 위한). 5.6. RPM을 제공하라 설치할 수 있는 바이너리 패키지의 사실상의 표준 형태로 레드햇 패키지 매니저, RPM이 사용된다. 가장 인기 있는 리눅스 배포본에 사용되며 다른 모든 리눅스 배포본(데비안과 슬랙웨어는 제외)에서도 사용된다. 따라서, 당신의 프로젝트 사이트에서 설치 가능한 RPM을 제공하는 것은 소스 tar 파일을 제공하는 것과 같이 바람직한 생각이다.