For every developer, git repositories are something that we deal with on an almost daily basis, but in reality most Git repository management is very casual and irregular. In some cases, this is fine, but as collaboration members grow and repository responsibilities expand, Many of the original non-standard small problems will be gradually amplified and even produce some very serious problems. In February 2018, my team, ICE, opened the alibaba/ ICE warehouse and reached the 1W + stars milestone at the end of 2018 after less than a year. In the process of managing the warehouse and operating the community, we have accumulated some best practices, both large and small. I hope to share this information to help other open source or non-open source Git repository managers. Note: I know I’m still in the early stages of git operation, so I’d like to point out any mistakes.

Split the warehouse reasonably

When we say warehouse management, in fact, it is not a single warehouse, but a product, a project or even a business, behind which there may be multiple warehouses or only one warehouse, so in the early planning to try to sort out, the core to avoid two misunderstandings:

Myth 1: Build a warehouse for every responsibility

This may be the intuitive response of most people, as this approach will rapidly increase the number of warehouses corresponding to products, resulting in a steep increase in long-term management costs:

  • Warehouse permission management is costly and confusing
  • Code development and submission costs are high
  • Issue /PR is too fragmented to manage statistically
  • …

In fact, when ICE was in-house, we developed a number of business components, each of which was a separate warehouse, and recently we had a lot of personal trouble doing unified upgrades (due to tool, specification, or other changes) :

  • Some components (repositories) are no longer maintained but do not have any markup
  • Group permissions are loosely managed, resulting in some non-official components
  • During the upgrade, you need to frequently switch warehouses

Therefore, we need to avoid too piecemeal management and then do the appropriate aggregation for the actual scenario.

Myth 2: All responsibilities are carried in one warehouse

In the front end community, this approach became more and more popular with the advent of Lerna, a mass distribution tool, and some of the hottest projects like Babel, React, jest, etc. gradually migrated to this solution. Aside from the capabilities provided by lerNA, this aggregated management approach saves warehouse managers a lot of costs, such as:

  • You only need to manage one warehouse
  • Issues /PR/wiki etc. are all managed in one place

However, this approach may go awry. As the author’s team, ICE, is a good example of how not to do it. After stepping into mistake # 1, we put all the packages in the same repository for the open source version, and then use the directory structure to ensure that responsibilities are clear. This method also brings a lot of convenience to our management as mentioned above, but after a year of iteration, we also encounter some problems:

  • More responsibility means more code, and as the history grows, the repository clone speed decreases, especially in small companies with slow networks (even with –depth).
  • The directory structure is relatively complex and not friendly to the community of students who want to contribute code

Therefore, we recommend “making another layer of separation according to responsibilities based on solution 2”. Combined with alibaba/ ICE warehouse, we will separate React material code, Vue material code and Angular material code into three independent warehouses in the future. On the one hand, we will reduce the volume of the main warehouse. Vue contributors, on the other hand, don’t need to care about other directories that don’t make sense to them.

Establish operational guidelines within the team

I had the honor to participate in the code specification of taobao front-end team and the implementation of relevant tools, so I know the importance of the specification to the team, and there are some principles for the formulation of specifications :(1) the specification should be correct first, and then improve the quality; (2) The specification should not affect efficiency too much (the trade-off between the two needs to be combined with actual scenarios). Here are some of the norms we are currently following:

Protect the branch

It is forbidden to submit code directly to the branch, which can be bypassed by the admin account in very special cases.

New Branch Rule

  • Branch names need to have semantics, such as ice-scripts/fix-foo-bug
  • If the requirements are simple and the time period is short, cut a branch from master directly, and then merge it into Master through PR. After the merge, release the version of the corresponding package
  • If the requirement contains multiple points of change, such as an Iceworks release, which often involves multiple function points, the development cycle is usually around a week, and if each PR is merged into the master, it is difficult to keep track of the overall progress. Therefore, we have the following agreement:
    1. The release branch (such as Release/Iceworks-2.16.0) should be cut from the master first, and then a base PR should be put forward. The PR should be supplemented with the list of features included in the current version and the order of release, etc. This PR is mainly used to manage the development progress of this version. Code does not need to be reviewed, and the release branch does not allow direct push of code
    2. Then each function change is cut from the release branch to the new branch, and PR needs to be merged into the corresponding release branch. The branch cut does not need to contain version information (such as iceworks/fix-xxxx).
    3. After all PR reviews are completed and merged into the release branch, release -> master’s PR is merged into release -> master’s PR. Need to make code changes again)

A commit message specification

A good Commit message will allow you to quickly understand the intent of the code, speed up the review process, and make it easier to trace the history of the repository in the future. The community has enough specifications for this to go through, so you can refer to the reference link at the end if you are interested.

PR merger process

Github offers three ways to merge PR by default. See the link at the end of this article for details on the differences. We think that Squash and merge are the most common options, because Squash merges multiple commits of the current PR. Make the entire commit history clearer, but we haven’t thought about whether we should merge the commit of each function point into a single release commit when we merge the release branch mentioned above into the master, so we’d like some advice or guidance. At the same time, when PR is merged, Reviewer is responsible for rewriting the Commit message to ensure more accurate semantics.

Here’s a little bit of history: In the early days github did not offer a squash merge approach. When we committed a PR to an open source repository, it was common to ask the committer to commit after the repository author review was completed. So a lot of people have googled “How to merge commit,” and now it’s just a click away, and that’s an example of how tools can improve productivity.

Release process

For those of you who are managing the toolkit, you should be familiar with and follow the Semver specification (the semantic version). This is the principle. On top of this, follow the following specifications:

  • Test version: The version number must comply with the rules of X.Y.Z-Nnpm publish --tag betaRelease, many students including myself often forget--tag betaI wonder if there is a more effective way to restrain?
  • The official version goes straight throughnpm publishRelease, and execute after releasetnpm syncSynchronizing an Internal version
  • After the official release, you need to create the corresponding Git tag. The tag naming rule is product name/X.Y.Z, for exampleIce - scripts / 1.0.2

Other unimportant things

How to ensure the standard landing

In combination with the implementation of the norms once promoted by the taobao front-end team and the norms currently developed by the ICE team, two conclusions are available for reference:

  • The specification needs to be accepted by the majority of people, and then iterates from loose to tight, and people grow with the specification
  • Small teams rely on literacy, large teams rely on tools: in a small team to develop norms, the need to do is to repeatedly emphasize, gradually let everyone form a habit; In large teams, it’s impossible to keep an eye on everyone, so you need tools like ESLint, commit-check, and process-strong tools like Door God

How do I iterate over historical versions

Let’s say I have a toolkit called ICE-Scripts that releases a break Change version 2.0.0 at 1.6.5. Normally we would iterate over the master branch (2.0.0 code). However, 1.x version may still be in use. How do we fix a bug in 1.x? Here’s a recommended process:

  • Start with git tagsIce - scripts / 1.6.5Cut out astable/ice-scripts-1.x(It would have been a bit of work to find the commit otherwise)
  • willstable/ice-scripts-1.xSet as the guard branch, which can be understood as the 1.x master branch
  • fromstable/ice-scripts-1.xCut new branchesice-scripts-1.x/fix-barAnd then modify the code to submit PR tostable/ice-scripts-1.xbranches
  • After the Review is complete, merge the code and thenstable/ice-scripts-1.xPublish on the branch

How to answer questions well

In the process of operating the community, users’ questions must be frequently faced. How to satisfy users while ensuring that their own investment does not affect the normal tools is extremely important. For technical products, according to the different user groups, there are currently two mainstream ways of answering questions:

  • Github issue: Pure asynchronous communication, to ensure that all issues can be resolved, and because of the cost of asynchronous communication, people will make a little effort to express their intentions, relatively higher quality of communication, but the response speed can not be guaranteed
  • Group of nails: synchronous communication, fast response, but for maintenance time is easy to break, reduce work efficiency

At present, the q&A section still takes up too much time on the whole, and this section is also in the exploratory stage:

  • Accumulate product and documentation
  • Nail group q&A on duty mechanism, each person is responsible for a day, each person needs to know more about the whole picture of the product correctly: in fact it will be a little difficult
  • Nailing robot problems precipitate
  • Introduce outsourcing mechanism

How to Manage An Issue

At present, THE overall issue management of ICE is not good. The author also started to manage this recently. Some suggestions are for reference only:

  • Strive to improve the quality of the issue through the issue template: The quality of the early issue in the ICE warehouse was very low, and many problems could not be repeated
  • The corresponding label classification is suggested based on the product classification. Each issue is associated with a label, and the corresponding person in charge handles it in a unified manner
  • The issue does not require timely treatment, but encourages quick clarification of the problem through communication or other means, so as to prevent a long time without understanding the description of the issue and then unable to communicate with the author of the issue

How to run a community

At present, THE ICE team maintains 5 answer-answering groups (each with 1000 people) and the official account of the technical forum, but the overall activity is relatively mediocre. At present, the ICE team is lacking in both energy investment and product operation experience, so we hope to get some suggestions or support.

Interesting robot

Github is full of handy bots (or apps?). , here I recommend two more useful robots:

  • Deletion-merged branch: After PR is merged, the branch is automatically deleted to prevent the accumulation of useless branches
  • Weekly Digest: Create an issue every week to summarize what’s going on in the repository during the week. For example: Weekly Digest (30 December, 2018-6 January, 2019)

Other interesting robots are welcome.

A link to the

  • Alibaba/ICE official warehouse
  • Write a good commit message
  • 5.1 Code Merge: select Merge and Rebase
  • Semver specification