커밋 히스토리를 사용하여 개발자에게 중요한 정보를 전달해야합니까?

최신 버전에서 타사 SDK를 롤백하는 회의에서 개발자가 커밋 기록에 이미 최신 버전을 사용해서는 안된다고 신고했습니다.

일부 개발자는 이것이 나쁜 습관이라고 주장했으며 대신 소스 파일 (예 :) // Don't upgrade SDK Version x.y.z, see ticket 1234또는 프로젝트 레벨 README파일 에 언급해야했습니다 . 다른 사람들은 커밋 히스토리가 프로젝트 문서의 일부이기 때문에 어쨌든 모두 읽어야하기 때문에 그러한 정보를 수용 할 수있는 위치라고 주장했다.

커밋 히스토리를 사용하여 중요한 정보를 다른 개발자에게 전달해야합니까, 아니면 해당 정보를 프로젝트와 같은 다른 위치에 복제 README하거나 관련 소스 파일의 주석을 사용해야 합니까?

최신 버전의 타사 SDK로 업그레이드하는 것을 살펴 보려면 마지막으로 소스 제어 시스템 의 역사 를 살펴보십시오 .

귀하의 제품이 SDK의 2.0 버전을 사용하고 있고 누군가 3.0으로 업그레이드하는 데 관심이 있다면, 소스 제어 시스템에서 시간이 거꾸로 돌아가서 그것이 좋지 않다고 생각하는 것이 합리적이라고 생각하지 않습니다.

여기에는 모든 개발자가 읽는 흥미로운 정보가 포함 된 소수의 페이지가있는 팀 위키가 있습니다 (코딩 규칙, 제품을 빌드하기 위해 개발 환경을 설정하는 방법, 설치해야하는 타사 항목 등). 이것은 타사 라이브러리 업그레이드에 대한 경고에 적합한 장소입니다.

확약 히스토리에는 기록해야하지만 통지를 넣는 가장 좋은 위치는 종속성을 정의하는 동일한 위치에 있습니다. 예를 들어 아티팩트 종속성을 선언하는 maven .pom 파일이 있으면 다음과 같은 작업을 수행합니다.

<!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 -->

<dependency>라인 바로 위에 있습니다 .

이슈 # 123에는 충돌 방식, 충돌을 일으킨 업데이트 버전에 대한 세부 정보가 포함되어 있으며 나중에 다시 방문하기 위해 백 로그에 다시 추가해야 할 수도 있습니다. 문제를 해결하는 또 다른 최신 버전이있을 수 있습니다. 티켓을 자동으로 편집하거나 직접 수동으로 팀에 이메일을 보내 현재 문제에 대해 알리고 추적기에 있으면 사람들이 나중에 다시 찾을 수 있습니다.

의존성 선언과 함께 사용하는 이유는 버전을 변경하려는 사람이 버전을 변경하려는 순간에 버전을보고 왜 변경해서는 안되는지를 이해하기 때문입니다.

누군가가 당신의 의존성을 검사하고 업그레이드를 시작하는 상황을 쉽게 이해할 수 있기 때문에 소스 코드에는 언급하지 않을 것입니다. 모든 TODO 주석에 대해 코드베이스를 검색 할 필요는 없습니다.

호기심 많은 개발자는 발행 티켓에 연결하여 어떻게 실패했는지 알고 나중에 다시 방문 할 수 있습니다. 이것이 없으면 상당히 정체되어 다시 업데이트되지 않을 수 있습니다.

정보를 고려할 때 사람들이보고있는 곳에 중요하고 직관적이지 않은 정보가 문서화되어야합니다.

내가 작업 한 팀과 프로젝트의 경우 새 버전이 실패한 이유에 대한 의견과 함께 롤백을 커밋했습니다. 새 버전이 수정되면 백 로그 스토리를 추가하여 업그레이드를 다시 시도합니다. 라이브러리가 연결된 빌드 시스템 / 빌드 스크립트에 주석을 추가합니다.

롤백은 미래 개발자에게 프로젝트 히스토리를 조사 할 때 컨텍스트를 제공합니다. 백 로그 스토리는 프로젝트의 일부로이 업그레이드의 필요성을 유지합니다. 빌드 시스템 주석은 라이브러리가 최종 업데이트 될 때 변경이 필요한 곳입니다.

코드에서 주석 처리하지 않고 README에 추가하지 않습니다. 업그레이드 시도를 생각하는 개발자는 이러한 부분을 보지 않을 것입니다. 거기에 추가하면 라이브러리 문제가 해결되고 업그레이드가 완료되면 제거해야합니다. 이 단계는 종종 잊혀집니다. 결과적으로 프로젝트에 반하는 메모가 작성됩니다.

프로젝트의 설정이 다르거 나 흐름이 다르면 답변이 다를 수 있습니다. 핵심은 개발자가 업그레이드 작업을 할 때 정보를 볼 수 있도록 정보를 올바르게 넣는 것입니다. 그렇게하면 업그레이드에 시간이 맞지 않으면 개발자가이를보고 중지하고, 시간이 맞으면 개발자가이를보고 메모를 제거하여 향후 개발자를 혼동하지 않습니다.

나는 그의 중요한 생각을 강조 하여 Matthew의 의견에 더 많은 관심 을주고 싶었다 . SDK를 업그레이드하지 않으려는 이유가 있으며 그 이유는 단위 테스트에서 캡처해야합니다. 개정 번호를 확인하는 것이 아니라 실제 근본적인 이유입니다.

예를 들어, 새 버전에 버그가 있다고 가정하십시오. 해당 버그를 확인하는 단위 테스트를 작성하십시오. 나중에 SDK에서 해당 버그를 수정하면 업그레이드가 원활하게 수행됩니다. 호환되지 않는 API 변경이있는 경우 코드가 새 API를 지원하는지 또는 SDK가 이전 API를 지원하는지 확인하는 테스트를 작성하십시오. 이는 단위 테스트보다 통합 테스트에 대한 것이지만 여전히 가능해야합니다.

우리 회사는 하루에 50 개 이상의 커밋을 생성하지만 우리는 정확히 크지 않습니다. 모든 개발자가 모든 단일 커밋 메시지를 읽더라도 솔직하게 말하지 않아도 기록 된 커밋 기록이 필요한 이유는 사람들이 메시지를 기억할 수 없기 때문입니다. 그리고 사람들은 문제가 없다면 나중에 돌아가서 역사를 읽지 않습니다. 그리고 아직까지 발생하지 않은 업그레이드 문제를 의심 할 이유가 없습니다.

반드시 가까운 시간에 작업이 중복되지 않도록 이메일을 보내어 빌드 스크립트와 README 또는 정오표에 기록하십시오. 그러나 특히 새 버전의 문제가 미묘하고 문제를 해결하는 데 시간이 많이 걸리는 경우이를 명확히하는 방법이 필요합니다. 그것은 단위 테스트를 의미합니다.

나는 "커밋 메시지를 통해서만 팀원들에게 발견 한 중요한 정보를 전달해야합니까?"라는 질문을 다시하고 있습니다. 나는 그것이 아니라고 생각하기 때문에 그렇게해서는 안됩니다. 나는 많은 의사 소통을 열심히하려고 노력한다 (이것은 대부분의 개발팀이 내 경험에 적극적으로 노력해야한다). 나는 함정을 피하거나 거짓말을 피하기 위해 최선을 다한다.

그러한 발견으로 이어지는 일련의 행동이 티켓에 의해 유발되면 티켓을 업데이트하고 (알아야하는 사람들이 가시성을 확보하도록) 아마도 얼굴을 맞대고 언급 할 것입니다 (호핑) 적어도 "Gee, Damon이 업데이트에 대해 말한 것 같다"고 잔소리가 나는 사람을 남겨두고 SDK를 포함하는 시점에서 아무도 업데이트 할 수 없도록 코드에 주석을 남길 것입니다. 그것을 볼 기회도없이 현재 팀이 아닌 미래의 고용을 염두에두고 더 많은 노력을 기울이고 있지만 개발 위키의 어딘가에 잼을 넣을 수 있는지 알 수 있습니다.

문제를 발견하고 발견하는 데 걸리는 시간과 비교하여 몇 분 더 걸립니다. 필자는 우리 문서 중 가장 적게 사용되는 신호가 적은 부분을 결정하지 않고 그대로 두었습니다.

커밋 히스토리에 있어야하지만 커밋 히스토리에만 있어야하는 것은 아닙니다. 잠시 새 개발자를 고용하십시오. 새로운 개발자가 프로젝트의 지난 10 년 동안 모든 커밋 메시지를 읽을 것으로 기대하십니까? 두 가지가 코드 기반을 이해하는 데 중요하기 때문입니다.

둘째, 상황은 코드가 변경되지 않는다고 말하고, "문서화"커밋을 수행하여 "개정 5432의 메시지 커밋이 잘못되었습니다. 현재 상황입니다."행에 커밋 메시지를 추가 할 수 있습니다.

팀의 커뮤니케이션 방식을 잘 모르겠지만 가장 효과적인 방법 은 팀의 이메일 그룹 에 먼저 이메일을 보내고 이메일로 "URGENT"라고 표시 한 것입니다.

여러분, 우리는 SDK v xyz를 사용할 수 없습니다. Foo 버퍼가 오버플로되고 Bar 서비스가 중단되기 때문입니다. 버전 xyy와 스틱

이것이 우리가 여기서 한 일이며 메시지를 전달하는 가장 신뢰할 수있는 방법입니다. 당신이 경우 정말 까다로운되고 싶어 (당신의 이메일 시스템이 허용하는 경우), 이메일에서 "읽음 확인"을 요청합니다.

팀 전체에 대해 이야기하면 팀 위키에 더 자세한 문서를 작성해야합니다. 문서 구성 방법에 따라 다릅니다. 응용 프로그램 종속성 및 요구 사항을위한 섹션이있는 경우 해당 섹션을 추가하는 것이 좋습니다.

이러한 종류의 문제를 문서화 할 수있는 추가 장소는 소스 코드 자체 일 수도 있지만 항상 작동하지 않을 수도 있습니다. SDK version ...하나 또는 두 개의 명백한 위치에서만 참조되는 경우 업그레이드하지 않는 것에 대한 메모를 포함 할 수 있습니다.

소스 제어의 파일 히스토리는 매우 길 수 있으며 개발자에 따라 하루에 여러 항목이있을 수 있습니다. 일주일 동안 휴가를 보낸 사람은 일주일 동안의 커밋 기록을 읽을 시간이 없을 수 있습니다. README 파일은 좀 더 중앙에 있고 사람들이 더 읽기를 원하는 경향이 있기 때문에 더 좋은 곳입니다. 그러나 모든 사람들이 실제로 README를 읽을 수는 없습니다 . 글쎄, 그들이 변경된 것을 볼 수 있다고 생각합니다 ...

커밋 주석에 이와 같은 내용이 포함되어 있어야하지만 다른 곳에서도 도움이 될 것입니다.

업그레이드하기로 결정한 사람은 사실을 알아야합니다. 그 사람은 소스 컨트롤에 살지 않을 수도 있습니다. 누군가 가이 문제에 대해 SO를 읽고 코드베이스에 넣지 않으면 어떻게 될까요?

이 타사 SDK에 대한 일종의 문서가 필요합니다.

• 어떤 문제가 해결됩니까?
• 왜이 특별한 것이 선택 되었습니까?
• 버전, 업그레이드, 테스트 등 고려해야 할 사항
• 누가이 결정을 내립니까?

이와 같은 것이 버전 관리에 들어간 사례가 있으므로 가능한 한 모든 사람이이 정보를 사용하도록 권장해야합니다. 귀하의 팀만이 문서, 소스 제어 또는 버그 추적기에서 누군가가 어디에서 검색을 수행 할 것인지를 결정하여 해당 주제에 대해 가능한 많은 정보를 얻을 수 있습니다. 그렇지 않으면 누군가 잊어 버릴 것입니다. 누군가가 누군가의 기억을 잃고 빨리 다시 롤백하면 운이 좋을 것입니다.

역사는 의도적으로 데이터를 찾는 독자를위한 데이터를 저장하기에 좋은 장소이며, 어디에 있어야하는지에 대한 일반적인 의미를 갖습니다. 검색하기보다는 사용자에게 제공해야하는 데이터를 저장하는 것은 매우 나쁜 곳입니다.

역사는 비교적 분류되지 않은 텍스트로 구성된 매우 큰 본문입니다. 일반적으로 개발자에게 변경된 내용과 변경된 이유에 대한 자세한 정보를 개발자에게 제공하기위한 것입니다. 찾고있는 것을 모르는 경우 정보 과부하가 될 수 있습니다.

사용자가 원하는 것을 모르는 경우 정보는 수백 개의 커밋 로그 아래에 빠르게 묻히고 그 앞에 정보 더미를 정리할 수있는 도구가 없습니다.

이 상황은 두 가지 기본 문제, 아마도 세 가지 문제가 있다고 해석합니다.

• 원치 않는 SDK 업그레이드로 인해 제품에 부정적인 영향을 줄 수있는 소스로 만들었습니다.
• 질문에서 : 원치 않는 업그레이드를 수행 한 기고자는 이전에 구체적인 업그레이드 결정에 대해 알지 못했습니다.

제 생각에는이 중 첫 번째가 가장 심각합니다. 원치 않는 SDK 업그레이드가 코드에 포함될 수 있다면 다른 문제도 발생할 수 있습니다.

누군가 업그레이드를 감지하면 실패하는 단위 테스트 사례를 추가 할 것을 제안했습니다. 업그레이드가 발생하는 것을 막을 수 있지만, 이것이 위험한 경로라고 생각 하며 시간이 지남에 따라 용암의 흐름 을 초래합니다 . 추후 언젠가 SDK가 업그레이드되어 새로운 기능이나 버그 수정을 가져 오거나 이전 버전이 더 이상 지원되지 않기 때문에 불가피합니다. 이러한 단위 테스트가 실패 할 때 발생할 수있는 헤드 스크래칭 (아마도 논쟁)을 상상해보십시오.

가장 일반적인 해결책은 개발 프로세스를 조정하는 것입니다. git의 경우 pull request 프로세스를 사용하십시오 . Subversion 및 이전 도구의 경우 분기 및 diff를 사용하십시오. 그러나이 일부 수석 개발자가 이러한 종류의 문제를 잡을 수 있도록 처리 하기 전에 그들이 코드베이스로 만들 다른 개발자에 영향을 미칠합니다.

풀 요청 프로세스가 현재 상황에서 사용되었고 각 풀 요청이 좁고 구체적이라면 시간이 많이 낭비되지 않았을 것입니다. SDK 업그레이드 요청이 제출되었으며 업그레이드를 원하지 않는다는 의견으로 거부되었습니다. 다른 사람은 영향을받지 않았으므로 이제 SDK 업그레이드를 되돌릴 필요가 없습니다.

그러나 원래의 질문에 직접 대답하기 위해 모든 개발자가 코드, 릴리스 노트 등의 전체 개정 내역을 완전히 읽는 것이 귀중한 시간 낭비라고 기대합니다. 짧은 팀 이메일에 어떤 문제가 있습니까?

가능한 세 번째 문제 : 왜 업그레이드를 원하지 않습니까? 분명히 적어도 한 명의 개발자가 업그레이드가 좋은 것이라고 생각했습니다. 업그레이드를 지연시키는 데에는 여러 가지 이유가 있지만 나쁜 것도 있습니다. 용암류 (불필요한 역 호환성 코드)와 화물 숭배 ( "그것을 업그레이드 할 수는 없지만 왜 그런지 모르겠습니다") 반 패턴을 피하십시오!

커밋 기록에 해당 유형의 정보를 추가하는 것은 괜찮지 만 여전히 올바르게 문서화해야합니다. 우리는 최근에 합류 (atlassian)를 사용하기 시작했습니다. 검색 가능하며 특정 페이지를 즐겨 찾기 등으로 설정할 수 있습니다.

다른 도구는 evernote 또는 Google 문서의 공개 노트 일 수 있습니다.

Karl의 답변을 확장 하여 체크인 프로세스 자체의 일부로 제한을 자동으로 적용하는 접근 방식을 사용합니다. doc / wiki / README 읽기와 같이 개발자를 대신하여 사전 조치가 필요하지 않으며 은밀하게 재정의 할 수없는 것이 필요합니다.

TFS 소스 제어 랜드에서는 체크인시 규칙을 실행하는 사용자 정의 체크인 정책 을 코딩 할 수 있습니다 . 예를 들어, 보류중인 체크인으로 구성 파일의 버전을 평가하고 xyz와 같지 않으면 실패하는 정책을 정의 할 수 있습니다. 이러한 규칙은 실제로 개발자가 체크인을 수행하지 못하게하고 설명 메시지를 제공 할 수 있습니다. 정책을 재정의 할 수 있지만 이러한 상황이 발생하면 경고를 생성 할 수 있습니다.

Karl이 언급했듯이 SDK 버전을 직접 또는 간접적으로 평가하는 단위 테스트 형태로 실패하는 gated-checkin이 대안이 될 수 있습니다.

이 답변은 매우 TFS 중심이지만, 현재 상황에 적용되는 버전 제어 / CI 시스템에 유사한 기능이있을 수 있습니다 (TFS가 아닌 경우).