Into the open source project - urlcat

Most people have a dream of participating in open source projects, but they don't know how to start the project before? Today, I was fortunate enough to encounter a library that I can start with — urlcat

urlcat is an open source project with only 267 lines of code, but it has received 1.4k stars and a weekly download of more than 1w. This is the open source project I have encountered with the least source code. The role of files in a project.

.github

In terms of naming, they are issue and pr templates. These three templates can effectively reduce the communication cost between authors and users and solve problems efficiently. Among them:

bug_report.md description:

1. what is the problem
2. How to reproduce the problem
3. What is the expected behavioral effect
4. screenshot
5. Desktop environment: what system, what browser, what version
6. Mobile environment: what device, what system, what browser, what version
7. Context of the question: Used to indicate whether the question is related to other questions

fate_request.md description:

1. Is the feature you need relevant to a problem
2. Describe the plan you want
3. Describe alternatives you may have considered
4. Describe prefab related functional issues

pull_request_template.md description:

1. Summary of the functionality of PRs
2. Detailed description of the PR

docs

The meaning of the existence of the project is precisely explained with What, Why, and How.

• What: what is it?
• Why: why do it?
• How: how to use

In addition, it also provides detailed api instructions and tells you how to participate in the project and contribute your own code.

src

source code analysis

test

It is said that unit testing is very important, but they all feel that writing unit testing is time-consuming and laborious. Even if it is just a few hundred lines of code, the author still writes such detailed unit testing. This is an attitude.

.all-contributorsrc

For a project to maintain its vitality and continue to develop, it requires the strength of everyone.

.editorconfig

Helps maintain a consistent coding style across editors and IDEs.

# 是否是顶级配置文件，设置为 true 的时候才会停止搜索.editorconfig 文件
root = true

[*]
# 换行符类型
end_of_line = lf
# 是否让文件以空行结束
insert_final_newline = true
# 缩进方式
indent_style = space
# 缩进大小
indent_size = 2
# 编码格式
charset = utf-8

.eslintignore

Tells eslint to ignore certain files and directories and not detect them.

node_modules
dist
coverage

.eslintrc.js

eslint configuration file

module.exports = {
  env: {
    'node': true
  },
  root: true,
  parser: '@typescript-eslint/parser',
  plugins: [
    '@typescript-eslint',
  ],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
  ],
  rules: {
    'object-curly-spacing': ['error', 'always'],
    'array-bracket-spacing': ['error', 'never'],
    'quotes': ['error', 'single'],
    'no-console': ['error'],
  }
};

There have been many good articles about the configuration of eslint. If you are interested, you can read this article.

related articles:

• ESLint configuration file.eslintrc parameter description

.gitignore

This configuration is useful when you need to ignore some files when submitting code

/node_modules
/dist
/dist-test
/.nyc_output
/coverage
.vscode

.npmignore

When you need to publish npm packages, you can ignore some files that do not need to be published to npm.

/node_modules
/dist-test
/src
/docs
/test
/.travis.yml
/tsconfig.json
/tsconfig-test.json
/.nyc_output
/coverage

.travis.yml

A configuration file for a continuous integration service

language: node_js
node_js:
  - lts/*
  - 14
  - 13
  - 12
  - 11
  - 10
script:
  - npm run lint
  - npm test
  - npm run coverage

Regarding continuous integration services, it is enough to read this article by Mr. Ruan Yifeng.

related articles:

• Continuous Integration Service Travis CI Tutorial

CODE_OF_CONDUCT.md

The first time I noticed this document, I searched for relevant information, and it turned out to be a code of conduct. Read the blog post to understand how it works. Codes of conduct have a vital impact on the health and sustainability of open source communities.

related articles:

• Code of Conduct

CONTRIBUTING.md

Contribution guidelines, mentioned earlier.

LICENSE

An open source license that authorizes others to use the product with specific rights. Avoid those who take it. How to choose an open source license, borrow a picture from Mr. Ruan Yifeng here.

related articles:

• How to choose an open source license?

README.md

The author's README.md basically covers all the content of the docs mentioned earlier, very concise, as concise as the code 😄😄

jest.config.js

The unit test configuration file, which is also what I lack, will learn more about it later.

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  coverageDirectory: 'coverage',
  collectCoverage: true,
  testMatch: [
    '**/test/**/*.ts'
  ],
  verbose: true,
  collectCoverageFrom: [
    '**/src/**/*.ts'
  ],
  testPathIgnorePatterns: [
    'dist.*\\.ts$'
  ]
}

related articles:

• Jest Chinese document

package-lock.json

Simple understanding, in order to lock the version number of the third-party package, since the project will depend on a large number of third-party packages, the third-party package will also depend on other third-party packages, when the package updates the incompatible api, after executing npm install, the project runs , unexpected situations may occur.

related articles:

• npm Semantic Versioning
• Package dependency difference between package-lock.json and yarn.lock

package.json

As a front-end person, we are all familiar with it, and share a few uncommon but critical configurations:

Specify the node version number:

{
  "engines": {
    "node": ">=8 <14"
  }
}

Specify the npm version:

{
  "engines": {
    "npm": "~1.0.20"
  }
}

If you plan to publish an npm package, the files field may be useful, specifying the file to publish to npm

Hooks, npm scripts have two hooks: pre and post . Its role is to execute some special commands to trigger automation scripts, for example:

• remove dist before build
• Run unit tests and package the project before publish

"scripts": {
    "clean": "shx rm -rf dist",
    "prebuild": "npm run clean",
    "build": "tsc -p .",
    "test": "jest",
    "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
    "coverage": "cat ./coverage/lcov.info | coveralls",
    "prepublish": "npm test && npm run build",
    "docs": "docsify serve docs --open"
  },

related articles:

• package.json detailed
• package.json you don't know

renovate.json

A feeling of déjà vu, it's it, it's it.

Renovate is an open source tool for automating:

• Detect dependencies in repositories (open source and private/closed source)
• Check for dependency updates
• Create commits and merge/pull requests to update dependencies
• ……

tsconfig.json

This configuration file is used when developing projects with typescript.

related articles:

• tsconfig.json configuration details

Summarize

In addition to source code and unit testing, the purpose of other files has been explained. It is not easy to do open source. When we got it at our fingertips, the authors of these open source projects paid too much. A group of people from all over the world, to accomplish one thing together, in addition to professional skills, see more of an attitude.

Reference article:

• ESLint configuration file.eslintrc parameter description
• Continuous Integration Service Travis CI Tutorial
• Code of Conduct
• How to choose an open source license?
• npm Semantic Versioning
• The package dependency difference between package-lock.json and
• package.json Detailed
• package.json you don't know
• tsconfig.json configuration