생성 된 문서를 Git 저장소에 저장해야합니까?

49

jsdocs 와 같은 도구를 사용하면 코드의 주석을 기반으로 코드베이스에 정적 HTML 파일 및 해당 스타일이 생성됩니다.

이 파일들을 Git 저장소에 체크인해야합니까 아니면 .gitignore로 무시해야합니까?

git documentation

— 쓰레기 수거
소스

3

pages를 사용하여 정적 HTML을 게시 할 수 있으므로 GitHub 리포지토리에 저장하는 인수가있을 수 있습니다 . 그러나 최신 등을 어떻게 보장하는지에 대해 완전히 분리 된 논증이 발생하지만 ...

— Boris the Spider

21

파일이 생성되면 소스 파일이 아닙니다 .

— chrylis

3

게시하려는 내용을 게시합니다. 특히 GitHub에서. 모든 사람이 생성 된 PDF 또는 이미지를 보도록하려면 모든 사람이 LaTeX를 설치하고 스스로 컴파일 할 것을 기대하는 대신 포함해야합니다. 예를 들어, 이 저장소는 생성 된 이미지를 포함하지 않고 프로젝트 파일 만 포함하면 매우 좋지 않습니다 ...

— Džuris

5

다소의 노골적인 중복 해야는 문서 버전 관리의 역사에 갈 생성?

— 모기

7

써드 파티 라이브러리의 소비자로서 온라인 문서가없는 라이브러리를 10 번 (저장소의 하위 폴더에 있든 또는 readme에 링크되어 있는지) 본 것보다 10 번씩 해당 라이브러리를 클릭하여 건너 뜁니다. . 라이브러리가 내 요구를 충족시키는 지 확인하기 위해 30 분 동안 Doxygen을 엉망으로 만들지 않을 것입니다.

— 알렉산더

131

특정 요구 사항이 없으면 버전 제어로 체크인 된 다른 파일을 사용하여 빌드 도구에서 빌드, 재생성, 구성 또는 생성 될 수있는 파일을 체크인해서는 안됩니다. 파일이 필요할 때 다른 파일에서 (재) 빌드 될 수 있습니다. 소스 (그리고 일반적으로 빌드 프로세스의 일부 측면 일 것입니다).

따라서 해당 파일은 .gitignore로 무시해야합니다.

— 프로그램 알람
소스

4

그러나 이는 빌드 도구의 버전 또는 빌드 도구의 가용성에 따라 달라질 수 있습니다 (예 : 일부 파일을 생성하려면 일부 이전 버전의 빌드 도구가 필요함). 어떻게 처리합니까? 당신은 당신의 대답에 그것을 해결할 수 있습니까?

— Peter Mortensen

27

@PeterMortensen 특수한 버전의 buld 도구로 빌드 된 아티팩트가 필요한 경우 필요한 빌드 도구 버전으로 빌드하십시오. 그러한 요구는 a) 자신에 의해 발견되며,이 경우 귀하는 귀하 자신입니다. b) README에 문서화되어 있습니다 ( "두 개의 특정 버전의 독소가 설치되어 있어야합니다 ..."); c) 빌드 스크립트가 처리합니다 (사용 가능한 빌드 도구 버전을 확인하고 적절하게 작동합니다). 어쨌든 소스 제어는 빌드 아티팩트가 아닌 소스에 대한 것입니다.

— Joker_vD

2

이 답변은 지속적인 배포 서버가 쉽게 액세스 할 수있는 방식으로 설명서를 작성하고 게시하는 경우에만 실행 가능하다고 생각합니다. 그렇지 않으면, 접근성을 향상시키기 위해 저장소의 문서를 "캐싱"하는 데 큰 가치가 있습니다. 소프트웨어 설명서를보기 위해 사용자가 빌드 스크립트를 다루지 않아도됩니다.

— 알렉산더

4

@Alexander 내장 바이너리를 리포지토리에 넣겠습니까? 설명서가 작성되었습니다. 빌드 된 문서를 가져 와서 어딘가에 액세스 할 수있게합니다.

— 1201 프로그램 알람

5

@ 1201ProgramAlarm "내장 바이너리를 리포지토리에 넣겠습니까?" 아닙니다. 빌드 바이너리는 문서와 비교할 때 GitHub를 탐색하는 사람들에게 선불 가치가 낮기 때문입니다. "당신은 내장 된 문서를 가지고 어딘가에 접근 할 수있게한다." 그것이 공개적으로 호스팅되고 눈에 띄게 연결되어 있다면 정말 좋습니다. 아마도 가장 좋은 경우 일 것입니다.

— 알렉산더

23

내 규칙은 리포지토리를 복제하고 "빌드"버튼을 누르면 잠시 후 모든 것이 빌드되는 것입니다. 생성 된 문서를 위해 이것을 달성하기 위해, 당신은 두 가지 선택을 할 수 있습니다 : 누군가가이 문서들을 생성하고 그것들을 git에 넣을 책임이 있습니다. 버튼은 내 컴퓨터에 모든 문서를 작성합니다.

생성 된 문서의 경우 헤더 파일을 한 번 변경하면 문서를 변경 해야하는 곳이 있습니다. 다른 개발자가 업데이트했을 때뿐만 아니라 항상 올바른 문서를 원하기 때문에 각 개발자의 컴퓨터 에서이 작업을 수행하는 것이 좋습니다. 무언가를 생성하는 데 시간이 오래 걸리고 복잡 할 수 있으며 라이센스가 하나 뿐인 소프트웨어가 필요한 경우도 있습니다.이 경우 한 사람에게 물건을 git에 넣는 책임이 더 좋습니다.

@Curt Simpson : 모든 소프트웨어 요구 사항을 문서화하는 것이 여러 곳에서 본 것보다 훨씬 낫습니다.

— gnasher729
소스

7

빌드에 필요한 (또는 적어도 무엇을 소프트웨어 누군가 문서화하지 마십시오 단지 문서) : 빌드 스크립트는 그가 실종 어떤 사용자에게 또는 그 합리적인 경우 자동으로 설치합니다. 저의 리 포지션 대부분에서, 모든 반급 유능한 개발자는 실행 ./Test하고 빌드를 얻거나 빌드를 얻는 데 필요한 정보를 얻을 수 있습니다.

— Curt J. Sampson

5

나는 당신이 지정한 경우 생성 된 문서를 git에 넣는 것이 좋다는 것에 동의하지 않습니다. 그것이 우리에게 인공물과 아카이브가있는 이유입니다.

— 술탄

그것은 당신의 규칙이고 좋은 규칙이며 나는 그것을 좋아합니다. 그러나 다른 사람들은 자신의 규칙을 만들 수 있습니다.

— emory

컴퓨터에 빌드 버튼이 없기 때문에 "빌드 명령을 실행하십시오"를 의미한다고 생각합니다. ... 전체 빌드가 IDE와 통합 될 것으로 기대하지 않는 한, 이는 전체적으로 불합리합니다.

— jpmc26

@ jpmc26 전체 빌드를 IDE에 통합하는 것이 전적으로 합리적이라고 생각합니다. 내 컴퓨터의 빌드 버튼은 Command-B입니다.

— gnasher729

14

이러한 파일은 생성 할 데이터가 이미 있으므로 체크인하지 않아야합니다. 데이터를 두 번 저장하지 않으려 고합니다 (DRY).

CI 시스템이있는 경우 해당 빌드 문서를 작성하여 해당 빌드를 위해 문서를 웹 서버에 게시 / 게시 할 수 있습니다.

— TVv1
소스

4

일부 저장소 (동일 또는 다른 저장소, 바람직하게는 자동으로 생성됨)에 배치하면 문서의 모든 변경 사항을 볼 수 있다는 이점이 있습니다. 때때로 이러한 차이는 소스 코드의 차이보다 쉽게 읽을 수 있습니다 (구체적으로 변경 사항이 아닌 사양 변경 만 신경 쓰면).

그러나 대부분의 경우 다른 답변에서 설명한 것처럼 소스 제어에 포함시킬 필요가 없습니다.

— 팔로 에베 르 만
소스

1

커밋을 만드는 데 사용되는 모든 리포지토리에 커밋 사전 후크가 거의 필요합니다. 문서 생성 프로세스가 완전히 자동화되지 않은 경우 문서와 코드가 동기화되지 않은 커밋을 얻게됩니다. 커밋 된 커밋은 커밋되지 않은 문서보다 이해력을 떨어 뜨립니다.

— cmaster

1

커밋 단계에있을 필요는 없습니다. 스토리지에 적합한 것으로 간주 될 때마다이를 게시하는 다운 스트림 / CI / Jenkins 작업 일 수 있습니다. 이것은 각각의 커밋 일 수 있지만, 정당한 이유가 없다면 결정을 분리해야합니다. 아니면 적어도 그것이 내가 보는 방식입니다.

— ANONE

3

무시되었습니다. 어쨌든 repo 사용자가 다시 빌드 할 수 있기를 원하며 문서가 항상 동기화되어 있는지 확인하는 복잡성을 제거합니다. 한 곳에서 모든 것을 갖고 있고 아무 것도 만들지 않으려면 내장 된 아티팩트를 한 곳에 묶지 않아도됩니다. 그러나 소스 리포지토리는 복잡성이 대부분의 장소보다 더 많이 손상되기 때문에 실제로 이렇게하기에는 좋은 곳이 아닙니다.

— 아무도
소스

2

배포 프로세스에 따라 다릅니다. 그러나 생성 된 파일을 저장소에 커미트하는 것은 예외이며 가능하면 피해야합니다. 당신은 다음과 같은 질문에 모두 대답 할 수있는 경우 예를 , 당신의 문서에서 확인하는 것은 유효한 옵션이 될 수 있습니다

문서가 생산을위한 요구 사항입니까?
배포 시스템에 문서를 작성하는 데 필요한 도구가 부족합니까?

이러한 조건이 충족되면 레거시 시스템이나 특수 보안 제한이있는 시스템으로 배포하는 것입니다. 또는 생성 된 파일을 릴리스 분기로 커밋 하고 마스터 분기를 깨끗하게 유지할 수 있습니다.

— 트렌드 피셔
소스

1

생성 된 파일을 릴리스 브랜치에 커밋하는 것이 모든 상황에서 작동하는 것은 아니지만 특히 마크 다운으로 작성된 정적 웹 사이트와 같은 경우에는 훌륭한 솔루션입니다. 빌드 프로세스의 일부로 이러한 커밋을 쉽게 생성 할 수 있는 특수 도구 를 빌드하기에 충분합니다 .

— Curt J. Sampson

2

따라 다릅니다. 그 문서가 있다면 :

와 같은 저장소의 일부가되어야 readme.md한다면 git repo에 보관하는 것이 좋습니다. 이러한 상황을 자동화 된 방식으로 처리하는 것은 까다로울 수 있기 때문입니다.
CI 시스템과 같이 자동으로 구축하고 업데이트 할 수있는 방법이없고 일반 사용자에게 표시되도록하려면 git repo에 보관하는 것이 좋습니다.
그것들을 만드는 데 많은 시간이 걸리고 유지하는 것이 정당합니다.
일반 사용자 (예 : 사용자 설명서)에게 표시되도록 만들어졌으며 빌드하는 데 상당한 시간이 걸리고 이전 문서에 액세스 할 수없는 (오프라인) 문서를 git repo에 보관하는 것이 좋습니다.
일반 사용자를 대상으로하고 변경 / 진화의 이력을 보여 주어야하므로 이전 문서 버전을 커밋하고 이전 버전과 연결된 새 버전을 빌드 / 커밋하는 것이 더 쉬울 수 있습니다. 정당하다.
모든 팀이 커밋되어야 할 특별한 이유가 있다면, git repo에 보관하는 것이 합리적입니다. (우리는 당신의 상황을 모릅니다, 당신과 당신의 팀은 않습니다)

다른 시나리오에서는 무시해도됩니다.

그러나 자식을 git repo에 보관하는 것이 정당하다면 팀이 직면하고있는 또 다른 큰 문제의 징조가 될 수 있습니다. (CI 시스템 또는 이와 유사한, 끔찍한 성능 문제가없고, 구축하는 동안 다운 타임이 발생하는 등)

— throawableAccount2892391
소스

1

버전 관리의 원칙에 따라 "기본 개체"만 "파생 개체"가 아닌 저장소에 저장해야합니다.

규칙에는 예외가 있습니다. 즉, 파생 오브젝트를 필요로하는 저장소 소비자가 있고이를 생성하는 데 필요한 도구가 없을 것으로 예상되는 경우입니다. 재료의 양이 다루기 어려운 것과 같은 다른 고려 사항도 중요합니다. (프로젝트가 모든 사용자에게 도구를 갖도록하는 것이 더 좋을까요?)

극단적 인 예는 컴파일러가 해당 언어로 작성된 희귀 한 프로그래밍 언어를 구현하는 프로젝트입니다 (잘 알려진 예에는 Ocaml 또는 Haskell이 포함됨)). 컴파일러 소스 코드 만 저장소에 있으면 아무도 빌드 할 수 없습니다. 가상 머신에서 실행할 수있는 컴파일 된 버전의 컴파일러가 없으므로 해당 컴파일러의 소스 코드를 컴파일 할 수 있습니다. 또한 언어의 최신 기능은 컴파일러 소스 자체에서 즉시 사용되므로 최신 버전의 컴파일러에 가깝게 빌드해야합니다. 한 달 전에 존재하지 않은 언어 기능을 사용합니다. 이 상황에서 컴파일 된 버전의 컴파일러는 반드시 저장소에 체크인하고 최신 상태로 유지해야합니다.

— 카즈
소스