GitHub에서 오픈 소스 자동화

개원을 유지하는 것은 숭고한 사업이지만, 아마도 시간이 걸리는 일일 것이다.그러나 꼭 그렇지는 않다.Hacktoberfest 2020년에 저는 제 저장소를 사용하여 jsx-readme의 공헌과 유지보수를 중심으로 자동화 실험을 했습니다.이것이 바로 내가 배운 것이다.

기부금을 쉽게 하다

오픈소스 프로젝트의 장점은 누군가가 기능 요청을 하거나 버그를 발견할 때마다 PR을 향상시켜 스스로 복구할 수 있다는 것이다. 적어도 이론적으로는 그렇다.실천 과정에서 많은 개원 프로젝트에 공헌하기가 매우 어렵다.공헌을 하기 위해서는

코드 라이브러리 이해,

을 로컬에서 실행,

은 어떤 기준을 준수해야 하는지 알고 있습니다.

좋은 CONTRIBUTING.md을 사용하면 이 모든 것이 매우 간단해진다.나는 여러 개의 대형과 소형 프로젝트를 훑어보고 a simple one을 만들었다.
그게 다가 아니야.코드의 구조도 이해하기 쉽고 공헌자들이 아무것도 파괴하지 않았음을 확보하기 위해 좋은 테스트를 거쳐야 한다.
또한 가능한 한 많은 규칙이 자동화된 방식으로 인코딩된다. 예를 들어 linting을 통해 투고자들은 PR을 쉽게 열고 피드백을 받을 수 있다.이것이 바로 왜 내 프로젝트에서 나는 항상 사전 제출 갈고리를 가지고 eslint --cache --fix을 운행하고 배치는 prettier을 포함하는가이다.이것은 우리로 하여금 생각하게 한다...

PRs 자동 검토

코드를 로컬에서 체크 아웃하고 실행하지 않고도 PR을 볼 수 있으므로 전체 프로세스가 훨씬 좋습니다.내 설정에서 나는 지금까지 PR이 하나밖에 없다고 생각한다. 나는 로컬에서 검사를 해서 스스로 조정할 수 있도록 해야 한다. 나머지 PR에 대해서는 코드 변경을 읽은 후에 그것을 받아들일 자신이 있다.왜?

저는 홍보를 하기 전에 반드시 문제가 있어야 한다고 강제로 요구합니다. 그러면 저는 먼저 무엇을 해야 하는지 토론한 다음에 홍보를 사용하여 어떻게 해야 하는지를 검사할 수 있습니다.

은 100%의 테스트 범위가 있으며 자동으로 실행됩니다.일반적으로 100%의 테스트 덮어쓰기율은 큰 도움이 되지 않을 수 있지만, 원본에 있어서 공헌자는 그들이 추가한 코드를 덮어쓰는 것을 테스트해야 한다는 것을 의미한다.CI는 이 두 테스트가 100%를 덮어쓰는지, 통과했는지 알려줄 것이다.그래서 복습할 때 나는 보통 먼저 테스트에 주목한다. 그들은 이번 호에서 토론한 모든 내용을 테스트했습니까?그리고 나는 유지보수성을 이해하기 위해 코드의 나머지 부분을 검사했다.마지막 단계로, 나는 테스트로 돌아갔다. 왜냐하면 때때로 코드를 읽으면 내가 확실하지 않을 수도 있는 가장자리 상황을 떠올리게 하기 때문이다.테스트 범위는 100%이고 범위는 높습니다.

코드의 스타일을 검사하지 않습니다. 이것은 이미 가죽과 미화에 주의를 기울였습니다.

자동화는 실천에서 어떻게 일합니까?나는 이전에 TravisCI와Circleci를 사용한 적이 있지만 작년에 GitHub 작업 흐름으로 바꾸었다.PR마다 tsc, eslint, jest, pkg-ok을 실행하고 모든 내용을 생성하고 컴파일하며 유형 오류를 표시합니다.tsc은 eslint 플러그인을 통해 옷감을 검사할 뿐만 아니라 스타일도 검사한다.prettier은 모든 내용을 정확한 위치로 컴파일할 수 있도록 단원 테스트(테스트 소스 코드)와 통합 테스트(컴파일된 코드에서 실행)를 동시에 실행한다.jest은 pkg-ok에 정의된 입구점이 존재하도록 확보한다.

문서 및 코드 동기화

소스 라이브러리를 작성할 때, 보통 다른 사람이 그것을 사용하기를 바란다.이것은 좋은 외부 문서가 필요하다.좋은 출발점은 예시가 있는 자술 파일이다.그러나 대다수 도서관에는 더 많은 것이 필요하다.
불행하게도, 문서는 곧 설명한 코드와 동기화되지 않을 것이다.소스 재구매 프로토콜을 유지할 때, 이상적인 상황에서 문서를 너무 걱정하지 않고 빠르게 변경할 수 있습니다.
그래서 package.json에 대해 저는 TypeDoc을 사용했습니다. 이것은 JSDoc standard을 기반으로 한 TypeScript 문서 라이브러리입니다(이것도 how React and JSX work together에 관한 것을 발견했습니다).이렇게 하면 내 문서가 코드 옆에 있습니다.

/**
 * Defines a regex to search with and a string that should be used
 * to replace the results found.
 */
interface Replacement {
  find: RegExp;
  replace: string;
}

/** @internal */
interface Props {
  fileName: string;
  children: string;
  replacements?: Replacement[];
}

/** Displays a code file with a heading and a codeblock. */
export const CodeFile: Component<Props> = ({
  /** The file's content. */
  children,
  fileName,
  /**
   * A list of replacements to be made in the file's content,
   * e. g. for replacing relative import paths.
   * */
  replacements = [],
}) => {
  function executeReplacements(str: string): string {
    return replacements.reduce(
      (replacedStr, replacement) =>
        replacedStr.replace(replacement.find, replacement.replace),
      str
    );
  }

  return (
    <Fragment>
      <Heading level={3}>{fileName}</Heading>
      <CodeBlock language={path.parse(fileName).ext.slice(1)}>
        {executeReplacements(children.trimEnd())}
      </CodeBlock>
      <LineBreak />
    </Fragment>
  );
};

타자 원고와 좋은 명명 덕분에 모든 것이 장시간의 묘사가 필요한 것은 아니다.jsx-readme은 fileName으로 별도의 문서 없이 이해할 수 있습니다.나머지 부분에 대해 우리는 코드 옆에 주석을 추가하고 the documentation will be created accordingly을 추가할 수 있다.이렇게 하면, 내가 (또는 처음 가입한 투고자) 새로운 도구를 추가할 때, 문서에 나타나고, 옆에 있는 기존 문서의 주석도 내가 필요한 모든 문서를 추가하도록 격려할 것이다.
그러나 코드에서 더 깊은 차원의 문서보다 더 중요한 것은 그 위의 자술 파일이다.이것이 바로 string 자신의 혜성이 있는 곳:

const Readme: Component = () => (
  <Fragment>
    {/* Create a header with title, badges and description inferred from package.json */}
    <TitleFromPkg pkg={pkg} />
    <BadgesFromPkg pkg={pkg} />
    {/* Add additional badges. */}
    <LineBreak />
    <DescriptionFromPkg pkg={pkg} />
    {/* Create an example section based on all files from the example directory set up in package.json */}
    <ExamplesFromPkg pkg={pkg} />
    {/* Create a section linking to the homepage from package.json */}
    <HomepageFromPkg pkg={pkg} />
    {/* Create a section linking to the contributing guidelines file */}
    <ContributingSection />
    {/* Create a section linking to the license file. */}
    <LicenseFromPkg pkg={pkg} />
  </Fragment>
);

void renderToFile("./README.md", <Readme />);

이것은 jsx-readme 및 샘플 파일에서 자동으로 생성되므로 파일 중 하나가 변경되면 읽어보기 파일도 변경됩니다.그 밖에 내가 사용한 예시 파일은 part of the integration tests이기 때문에 나는 이 예시들이 실제로 유효하다는 것을 시종 알고 있다.
마지막으로 가장 중요하지 않은 것은 합병할 때마다 자동으로 문서를 만들어야 한다는 것이다.이것은 스크립트의 도움으로 완성된 것이다

typedoc && touch docs/.nojekyll && ts-node examples/README.md.tsx

GitHub 워크플로우를 통해 실행되므로 이 문서의 뒷부분에 설명되어 있습니다.
내가 아직 설정하지 않은 것은 문서의 덮어쓰기 비율을 자동으로 검사하는 것이다.나는 이전의 소스 오픈 프로젝트에서 그것을 사용한 적이 있지만, 덮어쓰기 범위를 충족시키기 위해 무의미한 문서만 만들 뿐이다.

변경 로그 자동 작성

문서의 다른 부분은 변경 로그입니다.이 절차를 간소화하기 위해서, 나는 semantic versioning을 사용합니다. 이것은 내가 제출한 메시지에서 기계가 읽을 수 있는 형식으로 모든 변경 사항을 설명하는 것을 의미합니다.가장 큰 장점은 추가 문서를 유지할 필요가 없다는 것이다. 나는 제출에 따라 자동으로 변경 로그를 만든다.
그러나 이것도 단점이 있다. Git는 사용자에게 가장 편리한 도구가 아니다. 의미 있는 제출 메시지를 작성하는 것은 보기 드문 기능이다. 경험이 풍부한 개발자에게도 마찬가지다.나는 CI에서 PR의 모든 제출 메시지가 정확한 형식을 채택하도록 검사를 했지만 지금까지 갱신 제출은 PR 토론에서 가장 많은 시간을 소모한 부분이었다.

석방하다

공관은 받아들일 수 있다는 것을 알았으니 내가 해야 할 일은 심사 비준이다.기타 모든 것은 자동화됩니다.
mergify은 CI가 녹색으로 변하고 PR이 승인될 때까지 기다린 후 자동으로 결합합니다.
Semantic Release은 커밋 메시지를 읽고 새로운 버전이 필요한지(한 번 이상 커밋에 새로운 기능, 수정 또는 획기적인 변경이 포함된 경우) 및 업그레이드해야 할 버전을 결정합니다.변경 로그를 작성하여 모든 변경 파일을 게시 제출에 제출하고 게시 버전 표시로 제출합니다.마지막으로 가장 중요하지 않은 것은 npm에 발표될 것이다.이 모든 것은 대량의 플러그인의 도움을 받았다.

의존 관계를 최신으로 유지하다

마지막으로 가장 중요하지 않은 것은 소스 저장소를 유지하는 것은 의존 관계의 최신성을 유지하는 것을 의미한다.이 문제를 해결하는 가장 좋은 방법은 우선 의존 관계를 가지지 않는 것이다. 특히 자바스크립트 세계에서 이러한 방법은 여전히 충분히 이용되지 않는다. 모든 의존 관계에 대해 그것이 정말 필요한지 고려해야 한다. 왜냐하면 이것은 프로젝트에 나타날 뿐만 아니라 라이브러리를 사용하는 모든 프로젝트에 나타날 수 있기 때문이다.따라서 사용자가 설치해야 하는 모든 의존항에 대해 정말 필요한지 자세히 고려해 보십시오.
나머지 의존 항목에 대해 지금까지 우리의 설정은 매우 쉽게 최신을 유지했다. 나는 dependabot을 설정하여 새로운 패키지 버전으로 자동으로 PRs를 만들었다.100퍼센트의 테스트 범위이기 때문에 모든 테스트가 통과되면 PR을 통합할 수 있다는 것을 알고 있습니다. 이것은 제가 실제로 configure mergify을 자동으로 완성할 수 있다는 것을 의미합니다.그런 다음 GitHub 워크플로우는 해당 버전을 자동으로 작성합니다.

다음은요?

전반적으로 말하면 Hacktoberfest 기간의 실험은 매우 재미있었고 나는 나의 설정에 매우 만족했다.다음 단계는 프로젝트 템플릿을 만들어서 새로운 소스 프로젝트를 쉽게 만들 수 있도록 하는 것입니다.만약 당신이 아직 없다면, 언제든지 최신 소식과 인터넷 기술과 창업에 관한 더 많은 정보를 주목해 주십시오.
만약 당신이 이렇게 한다면 트위터에 당신이 개원 프로젝트를 유지하는 데 있어서의 경험과 가능한 한 아프지 않게 하는 방법을 알려주십시오.