Why standardize collaborative development?

If development is compared to driving a car, solo development is like a car on a wilderness road with no speed limit, no traffic lights, and no rules. It can speed freely and smoothly to its destination. Collaborative development, on the other hand, is like N cars driving on the traffic lines of a city, each with different starting points and destinations (like developers with different development tasks), and all want to reach the destination quickly (complete the development tasks). If there is no set of perfect traffic rules (traffic lights, traffic laws and regulations and other rules and regulations), each intersection will be jammed, traffic accidents will be frequent, and finally it is difficult for everyone to reach the destination smoothly (difficult to complete the development task smoothly).

It is as important to have a perfect set of traffic rules as to have a perfect set of traffic rules on the traffic line of a city. While the rules limit the speed at which some cars can travel, they allow most to reach their destinations.

The specification of multi-person collaborative development is to improve the overall development efficiency of the team.

There are many factors that affect development efficiency, such as:

  1. Development documents: Lack of or rough development documents such as requirement analysis, prototype drawing and design draft will lead to inconsistent understanding of requirements by product, design and developers, which is easy to cause rework;
  2. Project development mode: suitable development mode should be adopted according to the characteristics and types of the project, such as waterfall development mode, incremental development mode, agile development mode, etc.
  3. Technical framework/architecture: modular, componentized, or the original jQuery DOM operation mode;
  4. Code specification: unified code specification can improve code comprehensibility and maintainability and facilitate mutual code review among teams;
  5. Development process specification: how to manage branches, how to formulate Git submission specification, etc.
  6. Other factors: IDE, scaffolding, UI framework, code version management system (SVN \ Git), good development tools, can bring twice the result with half the effort.

Whether it’s solo development or collaborative development, the following are essential requirements for efficiency:

  1. Complete and perfect development documents;
  2. An appropriate project development model;
  3. An excellent technical architecture;
  4. A fully functional set of development tools;

However, a set of perfect code specifications and development process specifications are the key factors affecting the efficiency of collaborative development.

Compare the differences between multiplayer and solo collaboration:

Single-player development is usually more efficient than multi-player collaborative development, but the development cycle is often longer. In order to make the product quickly occupy the market, it is necessary to open the mode of collaborative development, as much as possible to shorten the development cycle. And how to make “1 + 1 equal to 2 as far as possible” and ensure effective human resource investment, we need to think about how to formulate a set of perfect multi-person collaborative development standards.

How to regulate collaborative development?

Common problems encountered during collaborative development

In order to avoid the above problems of collaborative development and improve the efficiency of collaborative development, the author, based on the experience of individual project development and team collaborative development, can gradually develop a set of appropriate standards for collaborative development from the following five aspects:

In each of these five areas, let’s take a closer look at how to build a multi-person collaborative development specification.

I. Task management

In the task management, the main consideration is how to transform the requirements into clear and orderly development tasks, and to effectively manage the development tasks.

The main objectives of task management are as follows: 1. Decompose the requirements, break down the large tasks into small tasks, let multiple people develop in parallel, and avoid code duplication and conflict as far as possible; 2. 2. Create tasks /issues and list detailed tasks for subsequent verification and tracking of corresponding functional codes; 3. Classify tasks to distinguish new function development, BUG repair and other task types; 4. Prioritize, clarify tasks at each stage, and ensure priority development of important and urgent tasks; 5. Divide the responsibilities of team members, formulate the task allocation & receiving mechanism, form the task kanban, and pay attention to the progress of project development.

The key path of task management: ① Task decomposition – > ② Task /issues – > ③ Task label management – > ④ Row priority – > ⑤ Assign & receive – > ⑥ Task Kanban

1.1. Task decomposition

Task management is the most important link in collaborative development, and task decomposition is the most important step in task management. Task decomposition has a direct impact on the effectiveness of collaborative development.

Typically we can split projects by business, by phase, by functional module, and by page.

For example, for an e-commerce project, we can split it into large business modules such as mall, supermarket, fresh food, livestreaming e-commerce, group grouping and social e-commerce by business:

According to the stage, namely according to the primary and secondary functions of the stage development, can be successively disassembled purchase process, membership module, shopping guide module, marketing module, etc. :

According to the functional modules, it can be divided into shopping guide module, shopping cart module, settlement module, order module, membership module, marketing module, etc. :

By page, for example, membership module can be disassembled into membership page, integral page, pre-deposit page, gift voucher page, address list page, address management page, etc. :

1.2. Tasks /issues

After completing the task decomposition, the requirements are transformed into smaller task lists. We can manage these development tasks by creating issues through GitLab or Github’s own Issues panel. When you create a task, list the task details and display the function points to be completed in the task list. In this way, we can get a clear development task list and quickly understand the code function details according to the task list of the Issue in subsequent code review.

Example of issue in Github:

1.3 Task label Management After we have the development task list, we also need to classify the tasks to distinguish the task types such as new feature development, bug fixing and feature improvement. You can set the following task labels: feat: Marks a feature development task. Bug: Used to mark bug-fixing tasks; Fix: used to mark tasks as historical functional improvements; Refactor: Used to mark historical feature refactoring tasks; Style: Used to mark refactoring class tasks for style.

1.4. Prioritize

After setting the task label, we also need to determine the priority of the task and output a list of tasks with clear function points and priority.

Set task priority by referring to Important & Urgent > Critical Not Important > Major Not Critical > Unimportant & Not Critical:

1.5 Task decomposition of assignment & collection is a time-consuming task, so the project leader can quickly decompose the task by task allocation + collection: The project leader only decomposed the task modules with larger granularity, and then assigned them to each developer, who then subdivided the task modules to build an issue with smaller granularity. The project leader reviewed the issue before development to ensure the rationality of the issue. Whether in assignment mode or pickup mode, divide up the responsibilities of each developer as far in advance as possible.

1.6. Task Kanban

Create a task kanban to keep track of ongoing tasks and estimate the progress of the current project based on the number of tasks to be completed and completed.

Gitlab comes with Issues Board functions:

Maintenance task kanban: 1. Set the corresponding task to the state of “under development” during development; 2. After the task is developed and merged into the main branch, set the task to the “Done” state.

Second, branch management

In the branch management, the main consideration is how to make full use of Git(distributed version control system) to ensure that all development members in the same project code orderly development work. The main objectives of branch management are as follows: 1. Assign fixed responsibilities to each branch and clarify the responsibilities of the branch; 2. Set permissions for the main branch to avoid code contamination of the main branch; 3. Develop in functional branches, and avoid multiple people working on the same functional branch at the same time, forming an orderly development branch line; 4. Functional branches should be associated with corresponding tasks for Code Review; 5. Ensure that development/testing/online can be carried out synchronously.

Key paths for branch management are as follows: ① Introduce/reference Git flow > ② Establish branch > ③ Set branch permissions > ④ Maintain branch

Git flow is one of the earliest and widely adopted workflow. Git flow has two main features: There are two permanent branches: the master branch, which is used to store releases, and the Develop branch, which is used to store stable releases at any given time. The latter is used for daily development and houses the latest development releases. There are three short-term branches, feature Branch, Hotfix Branch, and release Branch, that are merged into develop or Master and removed once development is complete.

Git Flow

By introducing Git flow workflow, each branch is given fixed responsibilities, and independent functional development branch is created to realize multi-person parallel development mode.

2.2. Establish branches by referring to Git flow workflow

  • Master main branch: used to store releases. Any time a release is obtained from this branch, it is a stable release.
  • Dev development branch: used to merge the completed function branch, store the latest development version of the code;
  • Feature branch start with Feature #. Create a feature branch associated with Issue #. For example, * Create a feature branch for task 3(Issue #3).
  • Release Branch: A pre-release version is required to be tested before an official release is released (that is, before merging into the Master branch). The pre-release branch is separated from the Develop branch and must be merged into the Develop and Master branches after pre-release.
  • Hotfix branch: a branch used to fix a bug during testing. This branch can be merged into the Master, Develop, and Release branches. For example, the branch used to fix bug133(bug #133) is named BUG #133.

2.3. Set branch permissions to protect the main branches (main branch, development branch), and only allow the main person in charge of the project to merge and push. Ensure that the Code submitted by the project developer is reviewed by the project lead before being merged into the main branch.

2.4 Branch maintenance Temporary functional branches need to be deleted in time to avoid excessive online functional branches and patch branches. There are two good opportunities to delete temporary branches: 1. When the functional branch requests to be merged with the development branch, the developer chooses to delete the temporary branch automatically after the merger; 2. After the function branch is merged into the development branch, the project leader will verify and delete it manually (the corresponding issue will be closed at the same time).

Code specification

In the code specification, the main concern is how to produce high-quality (understandable, maintainable) project code that is consistent with the code specification. The main goal of the code specification is to establish a uniform code specification and improve the understandability and maintainability of code.

3.1. Develop code specifications

As an example, you can specify HTML, CSS&SCSS, JavaScript code specifications, and constraints on the naming of various files:

1. Use soft TAB (4 Spaces) for indentation; 2. Add a blank line after the blank line variable declaration (no blank line is required if the variable is declared on the last line of the code block); Add a blank line before the comment (no blank line is required when the comment is on the first line of the code block); Add a blank line after a block (not needed in function calls, arrays, and objects); Leave a blank line at the end of the file; (3), and so on.

Standardize naming rules for directories and files: 1. Use lowercase names to separate directories. Example: my_project_name; When there is a complex number structure, use the plural nomenclature. Examples: scripts, styles, images, data_models 2.JS file names refer to directory naming rules. Account_model.js 3. And so on.

For more code constraints, see Airbnb Style.

We can also directly use the most popular code specifications on the market: Airbnb Style or javascript Standard Style. Instead of developing a set of our own code specifications from 0 to 1, we can directly use the existing code specifications on the market and the accompanying code specification inspection tool.

3.2. Check the code specification

After specifying a code specification, you can use ESLint to verify compliance with the specification.

ESLint is a assembler JavaScript and JSX checking tool that can be used to check current code specifications in real time at development time.

1. Install ESLint using NPM:

Node.js (>=6.14), NPM version 3+ $NPM install eslint --save-devCopy the code

2. Generate esLint configuration files:

$ ./node_modules/.bin/eslint --init
Copy the code

3, run ESLint on any file or directory:

$ ./node_modules/.bin/eslint yourfile.js
Copy the code

ESLint configuration files use names starting with eslint-config-, such as eslint-config-airbnb-base for the Airbnb Style specification ESLint rule configuration files. Omit eslint-config- when used, for example to configure using the Airbnb style specification:

// .eslintrc.js module.exports = { root: true, parser: 'babel-eslint', env: { browser: true, }, extends: 'airbnb ', plugins: [' HTML '], 'rules': {// store custom rules}}Copy the code

Specification using javascript Standard (ESlint-config-Standard)

// .eslintrc.js module.exports = { root: true, parser: 'babel-eslint', env: { browser: true, }, extends: 'standard', plugins: [' HTML '], 'rules': {// store custom rules}}Copy the code

We can also configure to use a custom code specification (eslint-config-xxx).

ESLint is mainly used to check for JS type code specifications. You can use StyleLint to check for CSS code specifications. StyleLint works in a similar way to ESLint. Please check the official manual (StyleLint) if necessary.

The basic format for automatically correcting code where Prettier is used. Prettier, which means “pretty, clever”, is the popular code formatting tool that parses code and reprints it using rules you create for yourself. Use instructions Refer to the official documentation (Prettier)

Git submission specification

In the Git commit specification, the main concern is to provide a more readable code commit record. The goals of the Git commit specification are: 1) To provide a more readable code commit record that is easier to understand when browsing the project history; You can filter certain commits (such as document changes) to make it easy to find information quickly. You can use the COMMIT Message to generate the Change log.

Currently, the most widely used Git Commit specification is the AngularJS Git Commit Message specification. Its Git Commit specification is reasonable and systematic, and has a complete set of supporting tools that we can refer to or use directly.

The AngularJS Git Commit Message specification: A Commit Message consists of a Header, a Body, and a Footer.

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
Copy the code

Type specifies the type of commit. Only the following 9 identifiers are allowed: Build: changes affecting the build system or external dependencies (example range: gulp, BROCCOLI, NPM) CI: Changes to CI configuration files and scripts (example range: Travis, Circle, BrowserStack, SauceLabs) docs will only change a new feature – fix bugs – perf code changes that improve performance – refactor code changes that neither fix bugs nor add features Changes that do not affect the meaning of the code (Spaces, formatting, missing semicolons, etc.) test: Scope is used to specify which page or module the current function point applies to. Subject is used for a short description of the current commit. Body is used for a detailed description of the current commit. You can split the Issue into multiple lines of a footer incompatible change statement, or close the Issue

Type, scope, and subject are mandatory, while body and footer are non-mandatory. Previously we created a list of issues with clear descriptions in task management and a functional branch associated with the Issue in branch management, so we can put the body and footer contents into the corresponding Issue description.

For example, after the completion of a function coding, Git submission, input:

Git commit -m "feat(新 页)Copy the code

4.2, Using an interactive Git commit tool We can use a commit specification helper (e.g. Commitizen) to make an interactive Git commit. Commitizen is a Commit Message tool that complies with the AngularJS Git Commit Message specification. It is easy to use. If you need to check out the official documentation (Commitizen).

With Git commit specifications in place, we also need a tool that can check whether Git commit messages conform to current Git commit specifications. Git commitLint + husky: Git commitLint + husky: Git commitLint + husky

npm install --save-dev @commitlint/config-angular @commitlint/cli
echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
Copy the code

2. Install Husky and do the following configuration in package.json:

// package.json
{
 "husky": {
   "hooks": {
     "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
   }
 }
}
Copy the code

Husky inherits all of Git’s hooks, and when it triggers a hook, husky can prevent a non-canonical commit.

5. Development process specification

In the development process specification, the main consideration is how to establish a clear, orderly, non-blocking development process.

Objectives of development process specification: 1. Establish clear, orderly and non-blocking development process; 2. Zero blockage in the development process; 3. Sustainable development/testing/launch.

5.1 Development workflow

Development work starts with an Issue and ends with feature development and merging into the development branch.

Development flow chart:

(1) After receiving the task, create the corresponding feature branch (Feature #xx) from the latest development branch; ② After the completion of the function development, the local development code before uploading synchronization operation; (3) When synchronizing code, the developer resolves code conflicts locally; (4) Initiate Merge Requests online with Code Reivew from the project leader or the person in charge of a business module; ⑤ Code Review: check whether the functions of the Code are complete according to the list of function points of the task. At the same time, you can also pull the branch Code of the function currently requested to merge to the local for preview and verification; ⑥ Merge branch: ensure that the function branch code without obvious problems can pass the merge request; ⑦ After the developer completes the feature development and initiates the merge request, he can immediately receive the new task (the next issue) and create a new function branch without waiting for Code Review.

5.2 Instructions for using related Git commands 1. When creating a functional branch, associate it with the corresponding Issue. After obtaining the task, when creating the corresponding function branch, the serial number of the function branch should be the same as the issue number of the task. For example, when obtaining the task 133 (issue #133), then create the function branch Feature #133:

Git checkout -b feature #133 # create a new feature branch from the development branchCopy the code

2. After completing the function development, submit the code according to Git submission standard format:

Git commit -m "feat(XXX 页)Copy the code

3. Before uploading the local code, carry out the code synchronization operation (synchronize the code of the latest online development branch to the current functional branch) :

Git fetch # Git rebase origin/dev # Git rebase origin/dev Git Rebase git Push Origin Feature #133Copy the code

5. When code synchronization occurs, if code conflict occurs, conduct git operation command after local conflict resolution:

Git rebase origin/dev # git rebase origin/dev Git add -a git commit -m "refactor(xx): Git push origin feature #133 Git push origin feat#133 -- -force # -- forceCopy the code

Use Git Rebase to synchronize code before uploading native code. This ensures that the code for each functional branch is based on the current dev branch.

5.3. Test and Launch Workflow Once each feature has been developed and integrated into the Dev branch, it is ready for testing. The purpose of testing is to find potential problems as far as possible before the project (or a functional module) goes live so that they can be fixed in time.

Flow chart of test work:

After the development of each function is completed, the dev branch is closed in turn. When all bug fixes are completed and verified, the online operation can be carried out.

On-line work flow chart:

In the development workflow, feature development is primarily coded on a separate feature branch (Feature #xx), which is merged into the Dev branch when completed. In the testing workflow, an additional release-x branch is created for testing, and bug fixes are also made on a separate bug branch (BUG #xx), which is merged into the release-x branch after completion. Finally, in the online workflow, merge the pre-release branch (relex-x) after the test to the master branch, and the latest code of the master branch can be deployed online.

Overview of development, testing and launch workflow:

As shown in the figure, the development, testing and launching can work in parallel in an orderly manner, and the requirements of different stages can be completed in the same period.

How to implement the multi-person collaborative development specification

There are many limitations for developers: 1. Code needs to be written according to uniform code specifications; 2. Code only in the function branch and bug branch; 3. Before submitting the code, synchronize the code and deal with code conflicts; 4. Git commit according to the specified format; 5. Code needs to be reviewed before it can be merged into the dev branch. Too many restrictions can easily cause resistance among developers, and it will be difficult to implement multi-person collaboration specifications in the early stage. Restrictions can be eased and gradually implemented.

Challenge of project leader 1. It is a challenging technical task to decompose complex large requirement tasks into simple small tasks; 2. How to quickly Code Review and avoid development process blockage. Improve the efficiency of Code Review by creating detailed issues and a readable Git submission record, as well as allowing the business module leader to share the task breakdown and Code Review related work.

In task management, we can not only use Issues Board of GitLab/Github, but also consider using professional task management tools to improve the quality and efficiency of task management, such as Tower and JIRA.

There is no one-size-fits-all solution in the world, and collaborative development specifications need to be adjusted according to the actual situation of the project and the number of developers. For example, for innovation projects within the department, because there is no professional tester involved, the way of developer cross-testing can be adopted. In branch management, there is no need to create additional pre-issued branches, and the bugs found by self-testing can be repaired according to the development mode of functional branches, and directly merged to the development branch after repair.

To make “1 + 1 greater than 2” The standardized method of multi-person collaborative development provided in this paper mainly considers how to make the efficiency of multi-person collaborative development “1 + 1 equals 2 as much as possible”, and how to make “1 + 1 greater than 2”, we need to think deeply about more factors. For example, precipitate reusable UI components, function modules, and quality project templates. Only through continuous accumulation in the actual practice of the project, can we continuously output reusable UI components, functional modules, high-quality project templates, etc., so as to continuously improve the development efficiency and achieve “1 + 1 is greater than 2”!

The reference list

  • Comic interpretation of software development model change history: www.tapd.cn/forum/view/…
  • Git workflow: ruanyifeng.com/blog/2015/12/git-workflow.html
  • A successful Git branching model: nvie.com/posts/a-suc…
  • Official website of ESLint: eslint.cn/
  • Deep understanding of ESLint: mp.weixin.qq.com/s/VSBrfCGm4…
  • Airbnb：github.com/airbnb
  • Standard JS：github.com/standard
  • Alloyteam code specification: alloyteam. Making. IO/CodeGuide /
  • StyleLint github.com/stylelint
  • Prettier: prettier. IO/and github.com/prettier
  • Contributing to Angular: github.com/angular/ang…
  • Commitlint: commitlint.js.org/#/guides-lo…

Related Open Source projects

AKFun is a front-end multi-scene packaging tool based on Webpack4.0 and rollup, supporting a variety of technology stacks: Vue technology stack, React technology stack, React&TS technology stack. Use AkFun to experience the capabilities of related tools like ESLint, Stylelint, Prettier, and CommitLint mentioned in the article. Github address: AKFun