친애하는 관리자님, 변경 로그를 저장하세요.

변경 로그.이것은 모든 프로젝트의 중요한 문서다.많은 항목이 하나 있다.많은 항목들도 최신을 유지하려고 시도한다.
그러나 상당수의 항목이 변경 로그가 없거나 변경 로그는 프로젝트 사용자에게 무용지물이다.
이 글은 엉터리 변경 로그가 프로젝트 소비자들에게 가져다 줄 수 있는 고통과 스트레스, 좋은 변경 로그가 프로젝트의 도입을 어떻게 도와주는지, 다음 프로젝트의 변경 로그를 자동으로 업데이트하는 해결 방안을 보여 주고 싶다.
알림: 소비자의 입장에서 볼 때 이 게시물은 약간 포효하는 것 같다.정기적으로 업데이트되는 PHP와 JavaScript 패키지에 의존하는 여러 항목을 유지 관리했습니다.일부 소프트웨어 패키지에는 엉망진창인 변경 기록이 부족해서, 이것은 내가 이 글을 쓰는 영감을 불러일으켰다.하지만 나도 자신의 개원 프로젝트를 발표하고 유지한다.그래서 나는 일의 양면을 안다.

로그 변경!=릴리즈 노트

변경 로그와 릴리즈 노트를 구분합니다.
변경 로그는 프로젝트 저장소의 단일 파일로 프로젝트의 모든 중대한 변경 사항을 포함한다.버전별로 그룹화됩니다.
릴리즈 노트는 GitHub 또는 프로젝트 웹 사이트에 게시됩니다.모든 버전의 하위 세트가 한 페이지에 표시될 수 있지만 일반적으로 각 릴리즈 노트는 개별 페이지에 표시됩니다.
릴리즈 노트의 내용은 해당 버전의 변경 로그와 같을 수 있습니다(예: 소규모 프로젝트의 경우).
비교적 큰 프로젝트는 일반적으로 장편대론을 써서 어떤 변화, 새로운 기능 배후의 동기, 협력자에게 주는 감사의 편지, 또는 중대한 변화가 생겼을 때 코드를 어떻게 업그레이드하는지 설명한다.
Tailwind CSS은 변경 로그와 발행 설명을 작성하는 데 모두 잘했다.
그들은 주요 버전과 부차적인 버전에 대해 상세한 발행 설명을 쓸 것이다.그들은 어떤 새로운 기능을 추가했는지, 예를 들어 이 기능을 어떻게 사용하는지, 또는 변경 사항을 완성하도록 지도할 것이다.(v2.2.0 또는 v3.0.0-alpha.1 릴리즈 노트 참조)
Their changelog은 "Keep A Changelog" 형식을 따릅니다.상단은 기본 분기의 최신 버전과 마지막 제출 사이의 비교 보기를 가리키는 미발표 제목입니다.모든 발표 버전의 제목에는 어떤 변화가 생겼는지 정확하게 보기 위한 링크가 첨부되어 있다.발표된 버전마다 변경 사항은 '추가', '변경', '복구', '삭제' 등 분류됩니다.변경 사항에 대한 정보를 더 알고 싶으면, 변경 사항마다 해당pull에 요청하는 링크가 있습니다 *요리사의 키스*
Tailwind CSS처럼 릴리즈 노트, 변경 로그 및 문서의 종속 항목을 올바르게 문서화하는 것은 즐거운 일입니다.관리자가 모든 정보를 제공했기 때문에 업그레이드에 필요한 시간을 최소화할 수 있습니다.

엉망진창인 변화가 가져온 고통

업무 중에 나는 PHP와 NPM 패키지에 의존하여 몇 가지 프로젝트를 관리한다.매달, 우리는 Dependabot에pull 요청을 만들어서 우리의 의존항을 업데이트하고, 나중에 볼 수 있도록 합니다.1
NPM 의존 항목의 심사 과정은 약간 혼란스럽다.
일부 NPM 프로젝트에는 변경 로그나 릴리즈 노트가 전혀 없습니다.복권을 사서 최상의 결과를 기대하는 것처럼 이러한 의존 관계를 업그레이드하고 최근의 제출을 보지 않는다.의존항은 여전히 예기한 대로 일합니까?npmjs에 발표된 코드입니다.com과github의 것은 같습니다.일반 도메인 이름 형식?업그레이드 패키지는 내 사이트에 악성코드를 배치합니까?
이러한 경우 저장소를 확인하고 최신 커밋을 확인합니다.만약 우리의 구축이 녹색이고 환매 협의에서 의심스러운 일이 발생하지 않는다면,pull 요청은 합병될 것입니다.단, 이 작업 절차는 변경 일지와 좋은 발행 설명을 제공함으로써 개선할 수 있다.
또 다른 흥미로운 pull request review 체험은mono repos에 있는 소프트웨어 패키지입니다.

위 화면 캡처는 @babel/core을 7.15.8에서 7.16.0으로 업그레이드해 달라는 요청을 보여줍니다.7.16.0 릴리즈의 릴리즈 노트도 볼 수 있습니다.
당신은 어떤 사람이 @babel/core을 언급하고 어떤 변화가 발생했는지 알아차렸습니까?릴리즈 노트 중 한 줄만 업그레이드를 시도한 @babel/core 의존 항목과 관련이 있습니다.남은 것은 소음뿐이다.
(이곳의 babel은 단지 하나의 예일 뿐이고 최근에 돌이켜볼 수 없는 의존항이다. 나는 바벨을 좋아하고 그 뒤에 있는 팀이 그것을 만들어 준 것에 감사한다. 모든 브라우저에서 새로운 자바스크립트 기능을 사용할 수 있기 전에 이 기능들을 더욱 빨리 사용할 수 있는 것이 좋다.)
너는 내가 여기서 NPM 가방만 언급한 것을 알아차릴 수 있을 것이다.
내 경험에 따르면 PHP 패키지의 문서 품질은 NPM/JavaScript 패키지보다 높습니다.아마도 이것은 PHP 가방이 보통 자바스크립트 가방보다'범위'가 더 넓기 때문일 것이다.몰라요.

솔루션

나는 이 글을 끝낼 때 변경 로그와 발행 설명을 더 잘 할 수 있는 방법을 제시하지 않으려고 한다.하지만 나도 모든 해결 방안이 없다.특히mono 환매 협의에서 언급한 문제는 내가 해결할 수 없을 것 같다.아니면 최소한 관리자한테는 안돼.(mono 환매 중 가방마다 단독 변경 일지를 유지하고 싶은 사람은 없다)
내가 자주 보는 자동 생성 발행 설명의 방법은 Conventional Commits을 사용하는 것이다.
제출마다 feat: 또는 chore:이라는 표기를 접두사로 한다.그런 다음 CLI 도구 또는 다른 소프트웨어가 마지막으로 릴리즈된 이후 커밋을 기준으로 변경 로그를 컴파일합니다.나는 개인적으로 아직 이런 방법을 사용한 적이 없다.처음 며칠 동안, 나는 제출 메시지에 탭을 추가하는 것을 잊어버릴 수도 있다😓.
내가 현재 사용하고 있는 방법은 release-drafter GitHub 조작과 GitHub의 라벨의 조합이다.release drafter는 병합 요청에 따라 변경 목록을 컴파일합니다.분기 이름, 요청 제목, 탭에 따라 통합된 요청을 분류할 수 있습니다.
요청이 잘못 분류된 경우 탭을 적용하고 업데이트하는 것이 매우 쉽기 때문에 다음 방법을 선택했습니다.나는 이미 이 방법에 관한 문장을 더 많이 썼다.
다음 권장 사항은 CHANGELOG.md 파일의 업데이트 프로세스를 자동화하는 것입니다.이를 위해 here이라는 GitHub 작업을 만들었습니다.
이 작업은 GitHub에서 새 버전을 게시할 때마다 트리거되는 워크플로에서 사용할 수 있습니다.이 동작은 지정한 발표 이름과 본문 텍스트를 사용하고 CHANGELOG.md 파일에 추가합니다.

name: "Update Changelog"

on:
  release:
    types: [released]

jobs:
  update:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2
        with:
          ref: main

      - name: Update Changelog
        uses: stefanzweifel/changelog-updater-action@v1
        with:
          release-notes: ${{ github.event.release.body }}
          latest-version: ${{ github.event.release.name }}

      - name: Commit updated CHANGELOG
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          branch: main
          commit_message: Update CHANGELOG
          file_pattern: CHANGELOG.md

내가 왜 이 동작을 만들었는지 더 알고 싶으면 changelog-updater을 읽으세요.어떻게 일하는지 알고 싶으세요?the introduction blog post 읽기.

이 박문 결론

나는 이 글이 발행설명과 변경일지의 중요성, 그리고 그들이 어떻게'소비자 만족도'를 높일 수 있는지, 그리고 관리자로서 이 문서들이 가능한 한 잘 되도록 하는 것이 가치가 있다고 보여주길 바란다.
만약 이 화제에 대해 생각이 있다면, 이메일이나 이메일로 나에게 연락할 수 있다.

GitHub에서 일부 요청을 처리할 수도 있음