블로그 게시물: 왜, 그리고 어떻게 좋은 변경 로그를 쓰는지

7276 단어 changesdocumentation
이 블로그에서, 나는 변경 로그를 어떻게 보는지, 그리고 변경 로그를 어떻게 작성하고 구축해야 하는지, 그리고 왜 작성하고 구축해야 하는지를 개술할 것이다.이것은 나의 경험과 관점을 바탕으로 한 것이지 최선의 실천이 아니다. 단지 내가 소프트웨어와 소스 소프트웨어를 사용하는 과정에서 변경 로그를 사용하고 생성하여 형성한 실천일 뿐이다.
소프트웨어 프로젝트를 만들 때, 크기를 막론하고 변경 로그를 쓰는 것은 좋은 생각이다.변경 로그는 일반적으로 스크립트, 라이브러리, 응용 프로그램과 함께 제공되는 단일 텍스트 파일에 표시되며, 이것은 소프트웨어 개발이나 프로젝트의 중심이다.
서면 텍스트를 통해 의사소통을 할 때 기대하는 정보를 성공적으로 전달하려면 몇 가지 중요한 관건을 기억해야 한다.

  • 텍스트의 독자는 누구입니까?

  • 왜 관중들은 본문을 읽고 있습니까?
  • 이것들은 모두 매우 기본적인 문제들이다. 답은 매우 단도직입적인 것 같지만, 당신은 글을 쓸 때 자신에게 이 두 가지 중요한 문제를 묻는 것을 기억합니까?특히 변경 일지는
    따라서 변경 로그에 쓰기 위한 설정을 설정해 봅시다.실제로 우리는 이야기의 형식으로 이 점을 묘사하여 기본적인 용례로 묘사할 수 있다.

    A user of my software is reading my change log to see if a earlier
    reported bug has been addressed


    우리가 이렇게 구체적으로 바라는 것은 변경일지의 역할을 이해하기 위해서이기 때문에 그 중요성을 이해하기 위해서다.
    변경 로그는 다른 문서와 구분할 수 있는 특정한 역할을 배치합니다.주요 문서는 소프트웨어의 이상적인 용도를 묘사했다. 일부 제한일 수도 있고 업무 목록, 튜토리얼 또는 다른 내용을 가리킬 수도 있다. 그러나 소프트웨어의 주요 용례는 다른 곳에서 묘사되고 소프트웨어를 자주 사용하여 업데이트를 한다. 이것은 변경 사항을 기록하지 않고 현재 상태를 기록한다는 것을 의미한다.이전 상태에서 이전하거나 기존 기능과 새로운 기능에 대한 반대나 소개를 전달했을 수도 있다.변경 로그는 소프트웨어에 변경 사항을 전달하는 데 단일하지만 매우 중요한 역할을 한다.
    구조화된 문서와 이와 관련된 소통 임무에 대한 상세한 정보는 본고의 범위를 넘어서 똑같은 방식으로 검사를 해야 할지도 모른다. 나는 문서에 대해 경험과 견해를 가지고 있지만 주제를 견지하자.
    주요 문서는 다음과 같은 용례에 사용됩니다.
  • 소프트웨어의 기능을 이해하고 심지어 그것이 어떻게 실현되었는지도 알 수 있다
  • 설치, 구성, 사용 또는 문제 해결 방법
  • 제거 방법
  • 지원 또는 담당자에게 연락하는 방법
  • 그러나 마이그레이션 및 폐기 정보와 같이 모든 것은 소프트웨어의 현재 버전과 밀접하게 관련되어 있습니다.
    또 다른 용례를 봅시다.

    A user of my software observes a problem, which points to my software.
    Instead of pouring over 1000s of lines of code, the change log is
    skimmed to see if any listed changes could be the reason to the problem


    이로 인해 소프트웨어 사용과 매우 관련이 있을 수도 있지만 다른 텍스트 통신과 관련이 있어 비상사태에서 사용할 수도 있는 또 다른 통신 관건이 생겼다.

  • 관중들은 언제 본문을 읽습니까?
  • 소프트웨어 문제나 비슷한 문제 때문에 열심히 일하는 사람이 있다. 아마도 초과 근무일 것이다. 그들은 스트레스에 직면해 있다. 시간이 이미 매우 늦었다.그들은 우리가 방금 묘사한 용례와 유사한 문제에 부딪혔고, 당신의 소프트웨어와 관련된 업데이트가 그들의 문제인지 아닌지를 가능한 한 빨리 찾아내야 한다. 그들은 다른 곳에서 해결 방안을 찾거나 스크롤을 실시하기로 결정해야 한다.
    이때 일지를 바꾸는 것이 도움이 되었다.
    변경 로그는 특정 표준 레이아웃을 따르는 변경 사항에 대한 간단한 설명으로 쉽게 사용할 수 있습니다.
    이제 이런 용례에 잘 적응하기 위해 변경 로그를 어떻게 구축해야 하는지 살펴봅시다.

    제목 추가


    파일 이름이 모호해서 파일 맨 위에 제목을 추가합니다Change log for ApplicationX

    시합에 참가한 작품은 제목과 항목별 목록의 형식으로 조직해야 한다


    항목은 설명된 버전의 지시로 시작해야 합니다. 이 예는 의미 버전 제어 (semver 를 사용합니다. 그 다음에 변경된 목록 항목으로 돌아갑니다.
    1.0.1
    - Fixed bug in parser
    

    시간을 거스르는 순서에 따라 항목을 정렬하다


    일반적인 용례는 최신 변경 사항을 발견하는 것이기 때문에 시간의 추이에 따라 역사적 변경은 점점 중요하지 않고 문서의 끝으로 이동한다.
    1.0.1
    - Fixed bug in parser
    
    1.0.0
    - Initial release
    

    제작 게시 항목


    게시 항목의 구조는 통일되어야 한다.
    적어도 다음을 포함해야 합니다.
  • 버전 번호
  • 타임스탬프
  • 의미 버전 제어를 사용할지 여부는 당신에게 달려 있습니다.그러나 각 버전을 고유하게 식별할 수 있는 버전 제어 체계가 필요하다.
    1.0.1 2018-09-27
    - Fixed bug in parser
    
    1.0.0 2018-09-27
    - Initial release
    
    시간대 스탬프와 시간, 분, 초 해상도를 보았습니다. 발표가 실제 작업에 똑같은 영향을 미치지 않을 수도 있기 때문에, 이 추가 정보는 좀 지나쳤습니다.
    날짜 형식과 일치하므로 ISO-8601 날짜 형식을 사용하는 것을 권장합니다.
    게시 유형에 대한 지침인 추가 메타데이터가 유용하다는 것을 알게 되었습니다.
  • 기능 출시
  • 유지보수 통과
  • 취약점 수리 발표
  • 이것들은 의미 버전 제어 방안에 직접적으로 비치지는 않았지만, 어떻게 발표하는지에 대한 정보를 제공했다.
    1.0.2 2018-09-27 Maintenance release
    - gitignore updated with tmp directory
    
    1.0.1 2018-09-27 Bug fix release
    - Fixed bug in parser
    
    1.0.0 2018-09-02 Feature release
    - Initial release
    
    사용자는 발표 설명을 보고 기능 발표에 포함된 기능이 이때 그들에게 유용한지 판단하거나 잠시 건너뛸 수 있다.
    만약 그것이 단지 유지보수 버전일 뿐이라면, 그것은 메타데이터나 발표 정보의 작은 문제를 해결했을 것이다. (나를 믿어라. 여러 해 동안 나는 이미 많은 것을 해 왔다.) 그러면, 지금은 아마도 그것을 뛰어넘을 수 있을 것이다.
    마지막으로 버그 fix 발표는 새로운 내용을 추가하지 않았고 이후 호환성은 완전무결하다는 것을 보여준다. 버그는 이미 해결되었기 때문에 문제가 해결되었는지 알고 싶은 시청자들에게 이 정보들은 주목할 만하다.
    일부 버그 복구가 중요할 수 있기 때문에 사용자가 발표할 때의 입장을 제시하는 것이 중요할 수 있습니다.
    나는 이 두 개를 사용한다.
  • 권장 업데이트
  • 업데이트 불필요
  • 1.0.2 2018-09-27 Maintenance release, Update not required
    - gitignore updated with tmp directory
    
    1.0.1 2018-09-27 Bug fix release, Update recommended
    - Fixed bug in parser
    
    1.0.0 2018-09-02 Feature release
    - Initial release
    

    구조 변경 항목 항목 항목


    이제 발표 항목 구조가 생겼으니 변경 항목을 살펴보자.
    게시의 단일 항목은 인간이 사용할 수 있도록 묘사해야 하고, 모든 변경 집합은 하나의 항목으로 묘사해야 한다.
    다음과 같은 항목이 표시됩니다.
  • 기능 추가
  • 오류 복구
  • 네, 이것은 전체적인 항목 구조 변경의 일부분이어야 하지만, 발표된 소규모를 유지하고, 이를 버그fix 또는feature release로 분류하는 것이 목표이기 때문에, 나는 가능한 한 그것들을 혼동하지 않겠습니다.
    주요 발표와 같은 비교적 큰 발표를 몇 번 했다면, 이러한 분리는 매우 유용합니다. 예를 들어 일반적인 계획 발표를 사용하면 매우 유용합니다.
    2.0.0 2018-09-27 Feature release, Update recommended
    
    Feature additions:
    - Added color selector
    - Added color profile exporter
    
    Bug fixes:
    - Addressed issue with start up time
    
    변경 로그의 모든 내용을 다시 쓸 필요가 없도록 링크와 인용을 추가하십시오.
    1.09 2018-05-30 Bug fix release, update not required
    
    - Based on issue #21 several issues with the test suite was spotted
      and corrected, at the same time there was created issues for
      implementation of adapters for SK and NZ. An issue with ES was also
      created since this distribution seems to rely on Date::Holidays,
      which does not seem to make sense.
    
      Ref: https://github.com/jonasbn/Date-Holidays/issues/21
    
    주동적인 태도를 쓰지 말고 수동적인 태도를 사용하세요.나는 사람들이 업무 목록이나 문제 추적 프로그램 등에서 직접 복제하는 것을 여러 번 보았다. 제출 로그에서도 이 점을 자주 볼 수 있다. 만약 네가 나에게 묻는다면, 이것은 완전히 경솔한 것이다.
    예:
    문제 추적기에서 다음 작업을 수행할 수 있습니다.
    색상 선택기 추가
    이것은 반드시 몇 가지 일을 완성해야 한다는 것을 나타낸다.
    변경 로그에 다음을 추가합니다.
    "색상 선택기 추가"
    이것은 어떤 일들이 이미 완성되었다는 것을 나타낸다.
    다음은 제가 기본 변경 일지에 대한 건의입니다. 이제 관련 정보를 말씀드리겠습니다.

    변경 로그 자동 생성


    제출 로그나 유사한 로그에서 변경 로그를 자동으로 생성하는 것을 몇 번 본 적이 있습니다.나는 이렇게 하는 것을 건의하지 않는다.
    변경 일지는 목록을 변경하는 것이 아니라 의사소통의 매개체로 중요한 역할을 한다.만약 당신이 이 일을 어디서 하는지 알고 싶다면, 나는 아래의 기준을 고려해야 한다고 생각한다.
  • 제출한 메시지가 충분한지 여부
  • 통합 또는 변경 세트를 트랜잭션으로 사용하시겠습니까
  • 너는 너의 버전 제어 시스템에서 메타데이터를 추출할 수 있니
    이것은 할 수 있다. 상기 두 가지 기준은 모두 정상적으로 규율을 약속하는 현명한 건의이다. 그러나 나는 충분한 성숙이나 규율이 엄격한 프로젝트에 참여한 적이 없다. 내가 이 점을 열심히 하지 않는다는 것이 아니라 어렵다는 것이다.
    그 중 하나는 변경 일지 인공제품의 생성을 누가 일하거나 처리해야 할지 결정해서는 안 된다는 것이다.하지만 변경 로그를 자동으로 생성할 수 있다면 알고 싶습니다. 듣고 싶습니다.

    바람이 불다 추가 알림: 가격 인하 기록


    이것은 정말 너무 많다. 예상보다 길게 썼지만, 나는 어쩔 수 없이 이 상금 정보를 밀어넣었다.
    가격 인하에 당신의 변경 일지를 쓰는 것을 고려하세요.
  • 이로써 링크가 더욱 짧아졌다. 이 링크들은 텍스트가 아닌 하이퍼텍스트로 나타난다. 네, 하이퍼링크가 멋있습니다. 감사합니다. 버너스 리 씨.
  • 필요하면 굵게, 기울임꼴, 코드 울타리
  • 를 사용할 수 있다.
    마지막으로, 다른 제목으로 발표 항목을 구성할 수 있으며, 부차적인 발표는 주요 발표에 포함될 수 있습니다.
    ## 2.0.0 2018-09-27 Feature release, Update recommended
    - Added colour selector
    
    ### 1.0.1 2018-09-03 Bug fix release, Update recommended
    - Fixed bug in parser
    
    ## 1.0.0 2018-09-02 Feature release
    - Initial release
    
    끝까지 읽어주셔서 감사합니다. 당신의 생각/문제 등으로 평론해 주세요.

    좋은 웹페이지 즐겨찾기