Ant Design submitted the code for the first time on May 7, 2015. All submissions and discussions took place on GitHub, with no Intranet version. Ant Design is a completely open source front-end project.

Based on Ant Design’s project operation over the years, this article will exchange the operation experience of open source projects with you. The main content will focus on project documentation, website, code specification and style, unit testing, release specification, open source project operation and other aspects, to provide practical guidance for you.

Project documentation

README

The README for a project should contain a core description of the project, including:

  • One sentence description: Solve what problem?

  • Badges: Is this a good project or not?

  • Features: What? What’s the difference?

  • How to use: What is a look

  • Necessary screenshots: What is a look

  • Development Guidelines: How to develop locally?

  • Reference Projects:

    • Standard – the readme (https://github.com/RichardLitt/standard-readme)

    • Ice (https://github.com/alibaba/ice/)

    • F2 (https://github.com/antvis/f2/)

To fit the document

In order to provide a pleasant development experience for programmers, it is important to use documentation quickly and with Steps by Steps.

  • README

  • Quick learning: step-by-step documentation, let users have a first impression (https://ant.design/docs/react/getting-started-cn)

  • Used in the create – react – app: alignment and community (https://ant.design/docs/react/use-with-create-react-app-cn)

  • Use: in the TypeScript and community alignment (https://ant.design/docs/react/use-in-typescript-cn)

  • Project of actual combat: for advanced users, promote Umi (https://ant.design/docs/react/practical-projects-cn)

Steps by Steps

FAQ

Collating official responses to common questions can save a lot of q&A costs. Contents can include:

  • FAQ document (https://ant.design/docs/react/faq-cn)

  • Components of the document FAQ section (https://ant.design/components/form-cn/#FAQ)

  • Issue tag (https://github.com/ant-design/ant-design/issues?q=is:issue+label:❓FAQ+is: Closed)

Key point: Keep up to date!

Badges

Badges are used to get an overview of the project by looking at some core metrics. Reference:

  • CI service 

  • coverage

  • npm

  • npm download

  • Dependent version (https://david-dm.org/ant-design/ant-design)

  • Gitter

  • Protocol Security (https://fossa.com/)

Use shields (https://shields.io/) and Badgen (https://badgen.net/) Badges to decorate your carefully written projects.

Web site

The site experience is the user’s first and possibly last experience. Features a basic website should have:

  • ⚛ Prerendered static site

  • 🌎 Internationalization

  • 📝 Markdown – -based documentation

  • 🎬 Examples with live playground

  • 🏗 Pretty Theme and Layout

  • 📱 Mobile friendly

  • 📖 API docs of easy to read and search

Static Website Construction

Web site can use bisheng (https://github.com/benjycui/bisheng), based on the React of SSR static site the generator:

  • static

  • Deployment solution: Use GH-Pages at first, switch to Netlify for domestic access speed, then go back to GH-Pages when you can’t afford Netlify, and use CloudFlare DNS to speed up service

  • Use gitee’s free Pages service (https://ant-design.gitee.io/index-cn)

internationalization

  • Documents, comments, feedback, Git messages, and issues are appropriate for foreign users

  • Website English and Chinese independent address convenient SEO

  • Community recruitment and guidance, over 70% of Ant Design’s English documentation is community contributed (https://github.com/ant-design/ant-design/issues/1471)

Document presentation and playground

Component demos should be friendly with real-time feedback:

Easy to read and search

Algolia can be used to implement the search function of the website:

Code specification and style

Code specifications are important, but don’t spend too much time on them. Use the tools 👇

 

  • eslint-config-airbnb

  • tslint => @typescript-eslint/parser

  • Prettier

Submit code

Make code submission fast and formal with two tools:

  • husky + lint-staged

  • Pretty – quick ⚡ ️

Commit specification


     
    
      
    git commit -a
    
     
Copy the code

     
    
      
    <type>(<scope>): <subject>
    
      
    / / an empty line
    
      
    <body>
    
      
    / / an empty line
    
      
    <footer>
    
     
Copy the code

  • A Commit message and Change the log writing guide (https://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html)

  • Automatically check commitlint (https://github.com/conventional-changelog/commitlint#readme), Examples of G2Plot reference (https://github.com/antvis/G2Plot/blob/da9a941b2921766b2f45e908d40e6ff73bc8d1db/package.json#L57)

Unit testing

Currently, there are two mainstream unit testing frameworks: JEST and Enzyme. Ant Design mainly uses JEST:

Watch mode

Fit, TDD artifact.

play

Snapshot

How are underlying dependency changes perceived? How are structural detail changes perceived? How difficult is it to write use case details? This can be resolved with snapshot:


     
    
      
    const wrapper = mount(<Breadcrumb />);
    
      
    expect(wrapper).toMatchSnapshot();
    
     
Copy the code


     
    
      
    NPM test -- -u // Update snapshot and commit
    
     
Copy the code

Coverage


     
    
      
    npm test -- --coverage
    
     
Copy the code

  1. If the overall coverage is not up to standard, CI will fail

  2. The coverage of the modified part of the code does not reach the overall coverage, CI will hang

CI service

CI can help us know what the status of a PR is, and whether this PR will introduce other problems. For PR contributors, this is a long list of things they did wrong and need to improve. Recommended CI services include:

  • Netlify web preview service

  • Surge web preview service

  • Bundlesize File size

  • WIP PR is in progress

  • Circle CI test case

  • Codecov test coverage

  • Codesandbox CI demo debug preview

More references: Miscellaneous Ant Design 4.0 – CIhttps://zhuanlan.zhihu.com/p/113537427 ）

Release the specification

Ant Design Rotation rules and release process (https://github.com/ant-design/ant-design/wiki/ rotation rules and release process), the core of which are:

  • Patch is released weekly

  • Minor releases monthly

  • It’s been released every week for the last five years, rain or shine, by rotating students

Issue and PR templates

Pre-verification helps users feedback problems more efficiently and reduces the cost of problem solving.

Merging branches

  • Creat a merge commit

    • Most secure universal, but one more merge COMMIT

  • Squash and Merge

    • Will lose details, not suitable for large PR, large branch merge will not use this

  • Rebase and Merge

    • The quality of each commit needs to be guaranteed

Some Git & GitHub tips

  • When obtaining the source code address, be sure to press y to fix the source code address.

  • Always close an issue with close #123 fix #23456 in git commit message to leave a valid trace in the corresponding issue.

  • Use git commit -a instead of git commit -m. You can add more information in the body.

  • Git pull –rebase And git cherry – pick.

  • Markdown Diff syntax.


     
    
      
    const a = () => {
    
      
    - const a = 1;
    
      
    + const a = '1';
    
      
    }
    
     
Copy the code

Changelog

Some core principles of Changelog:

  • If the minor version is to be released, create a PR to merge the feature branch into the master branch. All publishing operations need to be carried out on the Master branch. Attention! Do not use Squash merge! Prevent submission information from being lost!

  • Create a new release branch from master to make changes to the release (e.g. Git checkout -b release-3.6.0).

  • In changelog.en-us. md and Changelog.zh-cn. Md, you can use the compare function to find out the difference between the current version and the previous version, and feedback the valuable changes truthfully to the user.

  • Suggestions for unperceived changes to user usage (document fixes, minor style optimizations, code style refactoring, etc.) should not be mentioned to keep the content of CHANGELOG valid.

  • Write CHANGELOG from a developer-oriented perspective and narrative, without describing fix details, describing problems and their impact on developers. You can refer to the previous Changelog format.

  • When adding attributes, you are advised to use easy-to-understand language to describe the changes that users can perceive. (For example, add onCellClick property to define cell click events)

  • Try to give original PR links, PR changes submitted by the community plus links from the submitter.

  • To upgrade an underlying module to an intermediate version, look for changes in the RC-Component and explain the changes.

  • If you are unsure about the true purpose of the change, consult the submitter.

  • Refer to the previous version of log writing and add necessary screenshots to help clarify the new features.

  • Adding an emoji before each change increases the readability and vividness of the document, Optional emoji references are available here (https://github.com/ant-design/ant-design/wiki/ rotating rules and release process # emoji-for-Changelog).

  • Push release branch and initiate PR of CHANGELOG for other students to review.

  • The changed content of CHANGELOG is directly copied in the PR main building. The advantage is that the PR of CHANGELOG version will be associated in each issue. It is easy to know in which version the issue has been changed (https://github.com/ant-design/ant-design/pull/15018).

  • Changelog PR can be found at https://github.com/ant-design/ant-design/pull/12615.

There are two main points:

1. Describe the user’s first-scene problem, not your solution

  • ❌ fixes the DOM structure of the component Typography.

  • ✅ reconstructs and simplifies the DOM structure of List items and fixes missing Spaces in Item contents.

————–

  • ❌ Fixes style file path problems in lib.

  • ✅ Fixes missing component styles.

2. Write personal words for users

Major Upgrade

The goal is to help users mindlessly upgrade.

  • Upgrade manual (https://ant.design/docs/react/migration-v4-cn)

  • Earlier Version Documents

  • Console abandonment warning

  • The upgrade tools

    • migration-helper(https://github.com/ant-design/antd-migration-helper )

    • codemod(https://github.com/ant-design/antd-codemod )

    • Compatibility package (https://github.com/ant-design/antd-adapter)

Bot 🤖

  • ant-bot

    • Automatically close non-standard issues (use service experience for service efficiency, not recommended as a last resort)

    • help wanted  Need Reproduce Help wanted  Usage

    • Assign handlers randomly

    • Automatically reply to the mirror site

    • Release synchronously when the pin group

  • GitHub Actions

    • CI test cases

    • Deploy the site automatically when a new version is released

    • Synchronous gitee

  • Probot (https://probot.github.io/apps/)

Collect feedback

Hotjar provides useful features such as surveys, feedback channels, hot spot statistics, and so on. The free version is pretty much what you need.

Contribution to guide

  • Local debugging makes it easier to contribute

  • Guidelines for submitting PR how to fix CI

  • To attract community Collaborators, there are now 12 west Collaborators on the official team, Has been is the main force of maintaining (https://github.com/ant-design/ant-design/wiki/Collaborators#how-to-apply-for-being-a-collaborator)

  • Donation channels (https://opencollective.com/ant-design) can purchase some to use open source according to the income paid services for project

Open source project operation

Operating channels

  • Zhihu 🔥 is the most professional website in China with social broadcasting capability

  • Gold digging & open source China 🔥 more entry-level users

  • Hacknews 🔥 Top tech list

  • Reddit: 🔥

  • Dev.to 🔥 foreign edition nuggets

Operational skills

  • Do SEO (search engine traffic without money, long flow)

  • Various promotional articles (keep appropriate exposure)

  • Awesome List (where there’s gotta be you)

  • Rub against competing products (competing products is a very happy thing)

The surrounding

You go where your users are.

  • The scaffold

    • create-react-app-antd(https://github.com/ant-design/create-react-app-antd )

    • Next.js(https://github.com/zeit/next.js/tree/master/examples/with-ant-design )

    • react-boilerplate(https://github.com/ant-design/react-boilerplate)

    • react-starter-kit(https://github.com/ant-design/react-starter-kit )

    • parcel-antd(https://github.com/ant-design/parcel-antd )

  • Theme/color/icon

  • Sketch & Axure

  • Other Technology Stacks (Angular/Vue)

  • Non-mainstream build tools

Open source is a service industry

Service definition:

A service is something that the public needs….. which is provided in a planned and organized way

The enterprise culture of the service industry, popularily speaking, is service-oriented, including service standard, service concept, service purpose and service effect. Baidu Baike

Either answer user questions or provide services that are planned and organized.

conclusion

  • Embrace the community and stay engaged

    • Customer first, improve team influence with word of mouth

    • Keep up with technology

    • Transparent and open processes

  • Take advantage of the various services and tools available in the open source community

    • Improve code and engineering quality

    • Reduce maintenance costs

  • Single Source of Truth

    • Intranet and Extranet alike

    • GitHub is a much better experience than LinkE

  • Business is king (this is the most important one, the above can forget, this one should not forget)

    • As the saying goes: business out of step dies fast

    • Open source projects don’t die because open source isn’t good, but because internal sources no longer rely on the open source version

    • Serve internal business with open source software delivery processes

You might also like 👇👇

2020 Technology outlook in the field of front-end open source

Benefits to the

Blockbuster download!

2020 Required Manual for Front-end Engineers

Alibaba front end Committee recommended! Covering the language framework, front-end intelligence, micro front-end, Serverless and engineering 5 hot front-end technology direction, 10+ core combat front-end manual, unlock the new way of front-end, mining the new ideas of front-end, at this moment, to get a sneak peek! Follow alibabaf2e wechat official account to reply to the required manual to get the download link now.

Focus on Alibaba F2E

Grasp the new trend of Alibaba