preface

I’ll give you a Versailles introduction.

Hi everyone. I am a Member of The GitHub Flutter Team and one of the main collaborators on Flutter.cn and CFUG. I am good at persuading new Flutter developers to quit, executing garbage code on Flutter veterans, and convincing Flutter developers to make a rat tail.

Since entering Flutter 19 years ago, 8 PR (not many) have been submitted for Flutter, including 2 breaking changes, 2 style changes, 2 feature fixes, and 1 SDK author list addition. Some PR’s are easily resolved, some are closed for various reasons, and some involve a lot of discussion. With the exception of easily merged PR, most PR points to one word: hard.

I’m going to show you how hard it is.

Step 1: Find a point where you can PR

Trust me, this is definitely the easiest step you can take to Flutter PR. Because all SDK content for Flutter is open source, every developer can view any line of Flutter source code anytime, anywhere.

It’s easy to find a mistake in all this. An 🌰 :

There are more or less hidden document errors in Flutter. One day, if you look through the document and look through the source code, you may find some minor errors immediately. Bam! It’s worth finding out, but don’t use it for PR because it doesn’t work. Write code to speak code.

Here’s another 🌰 :

One day you are playing the Flutter Gallery and suddenly realize: “Gosh, this icon means the opposite! This must be a mistake! 👴 🐛!” Then excitedly prepared to submit a PR.

Good. So what are we going to do?

Step 2: Prepare a copy of the project

Friends who have done PR for other projects should be familiar with the process, here is a brief introduction.

• Fork Project repository
• Create a repair branch
• Submit changes
• A PR
• Waiting for review and processing

If the changes are small and you are familiar with GitHub, you can complete the changes completely on the web without pulling the whole Flutter SDK locally (because the repository is large and well understood).

For major changes, follow these steps:

• Pull fork’s repository locally
• Configure remote upstream to branch to github.com/flutter/flu… Easy to handle file conflicts
• Local new branch ready to start changes

Step 3: Understand code specifications and codes of conduct

Code specification

Unlike the familiar formatting of DARTFMT, Dart Format, and Flutter Format, to commit to the Flutter repository, no line of your code can be formatted using a formatting tool. Specific code Style instructions for Flutter repo are in the Style Guide for Flutter. Formatting of old code is not considered when making changes, unless you want to fix old code.

For a simple 🌰 (non-empty security), here is a StatelessWidget formatted by a tool:

class AWidget extends StatelessWidget {
  const AWidget({
    Key key,
    @required this.b,
    this.c,
  })  : assert(b ! =null),
        super(key: key);

  ///.
}
Copy the code

The code that Flutter requires in the SDK looks like this:

class AWidget extends StatelessWidget {
  const AWidget({
    Key key,
    @required this.b,
    this.c,
  }) : assert(b ! =null),
       super(key: key);

  ///.
}
Copy the code

Keep your eyes wide open, or you may soon be asking: What’s the difference?

Note the assertion and the code for super, Flutter requirements, missing a space ☝️. (A billion little details)

Generally, minor or larger changes will encounter formatting errors after the first commit. In this case, you can find the Linux ANALYZE task in the CI list that has submitted the corresponding PR to view the details of the noncompliance. If it doesn’t go wrong, congratulations, your format is 80% compliant with Flutter requirements.

The code of conduct

Flutter provides a Code of conduct for all contributors.

Make sure you read and understand the guidelines carefully before you start making changes.

Step 4: Make sure the new code is tested and passes all tests

After you’ve made your changes, you may feel like you’re done. But this is really just the beginning.

All changes (except for some document typos) need to include tests. The Flutter SDK repository also contains all historical tests. Each corresponding file has the corresponding feature test, Golden test, and Regression test.

Writing tests is a relatively difficult step, but Flutter actually has the right tools to test your code. At this point you need to test your new code by referring to the corresponding tests for the location where you commit the changes, for example: Dart you updated the lib/ SRC /material/text_field.dart code, so you should reference similar tests in test/material/text_field_test.dart. For information on how to use the Flutter testing tools, learn how to test your code at 🔍 and the Flutter Unit Testing Cookbook.

If your change includes some behavior change that ultimately causes some old tests to fail, that change is a breaking change. Destructive changes require some additional steps to handle.

Before uploading your code, be sure to run all of the flutter built-in tests locally with a FLUTTER test. If you find tests that don’t pass, try to fix them before you commit.

Next, let’s move on to the next step.

Step 5: Commit your changes to Flutter

To github.com/flutter/flu… , you’ll see a prompt that you just committed to a branch of your forked repository, leading you to do PR. Click Submit to enter information filling.

You’ll see that the PR template creates a lot of content for you, It includes five aspects: Description, Related issues, Tests, checklists and Breaking Change. Specific do not repeat, according to the content can be filled in (read do not understand the translation, translation do not understand goodbye 👋). Click Create Pull Request to open PR. The PR content after opening is similar to the following (there was no need to write a description at that time, just link to the issue) :

If your PR does not already include tests, you will see the following message reminding you that you need to add tests. If you really, really don’t need to test and need to apply for an exemption, you need to use Discord to go to Flutter’s # Hackers -💭 channel and apply with @hixie.

One caveat here is that Flutter merge PR is squash merge, which means that all your submissions in the process are merged into one, so we don’t have to worry about what is often called dirty PR. But submitting to specifications is an essential quality for participating in open source project maintenance.

Step 6: Sign the Contributor License Agreement

Before submitting your code to Google’s repository, you need to confirm and sign the Google CLA (Contributor License Agreement).

In cla.developers.google.com/ for signing. When you’re done, go back to PR, @Googlebot and say @Googlebot I signed it!

If Googlebot tells you CLAs look Good, your CLA has been signed and the next step is to wait for the official review.

Step 7: Reviewers to discuss your PR

This is the hardest part of PR. Not everyone will understand your purpose and outcome the first time they see the code, so a reviewer may have some questions or a different idea.

Of course, there may be confusion with a reviewer (s), so don’t be afraid to correct. Be sure to state your opinion clearly and reasonably.

With a reviewer’s opinion, you will need to provide some answers to further clarify your thoughts. Also consider carefully whether the other person’s proposal is feasible and better.

Step 8 (Disruptive change) : Write the design document

A Design doc is a Design document in which you propose destructive changes. The design document is mainly to explain the details of your changes, This typically includes a Summary, Objective, Background, Overview, Detailed Design, Open Questions, and migration plan (Migration Plan). Please refer to the official template of flutter. Dev /go/template

I have written design documents: docs.google.com/document/d/…

Step 9 (Disruptive change) : Write a migration guide

The Migration Guide is a guide to the changes you need to make and how to migrate them. If an API is deprecated as part of your changes, then in the migration guide you need to give explicit code for migrating from the old API to the new API for developers to use. All Migration Guides are listed on the website: flutter.cn/docs/releas…

The migration guide I wrote: github.com/flutter/web…

Step 10: Be prepared for A PR shutdown/delay

Some programmer insisted THAT I write this section. It is true that giving A PR to Flutter does not guarantee that it will be approved by a member. There is a 50% chance that the PR of Flutter will not be approved. As I said in my communication with KC in July this year, many times you cannot know what the official Flutter wants. As a result, your original intention may not be accepted, or the official will recommend you to implement your changes in another way, and your PR will be closed.

In the past two years, candy members have given Flutter a lot of PR. To pick one of the best, it is the Fallwaterfall widget for Flutter: github.com/flutter/flu…

Why was it shut down? Because officials say they want the core framework to only provide the infrastructure for building widgets, all style widgets are managed as a package. It may sound silly, but on closer inspection you have to agree with the official view.

And a very classic PR: github.com/flutter/flu…

Official explanation: by design. Since then as Design has spread in the community as a Flutter stem…

Since Flutter introduced Flutter -bot to help merge requests, there has been less procrastination. Otherwise you don’t remind them, they will completely forget, let’s take a look at dragon general PR: github.com/flutter/flu…

Step 11: Wait for the merger + follow up

After all the above steps have been completed, your PR will finally have a waiting for Tree to go Green tag:

When your PR is tagged, the BOT will automatically merge your PR when the Flutter Build is normal. Once you’ve done this, congratulations on successfully submitting code for a framework used by millions of people

But don’t think it’s over. With luck, your PR won’t fail any internal tests, and nothing will happen. But if any of the internal tests fail, your PR will be restored (though it will eventually land again).

In addition, if your patch accidentally produces some unexpected behaviors, it may also cause extensive issues and official notification to remind you to follow up.

conclusion

PR is slow work, so is submitting code for large projects, and collaborating with others in the open source community is an art form. Normal PR may take only 5-6 steps to complete, but dealing with Flutter requires much more thought. During the heyday of Flutter, the community environment in The country was very friendly and active, and more and more people gave back to Flutter itself. I also hope that more developers can actively feedback.

Compared with the difficulty of Flutter warehouse, Flutter.cn/dart.cn is much easier. We welcome all of you to collaborate with Flutter, synchronize and translate official documents, to bring more convenient and practical development experience to domestic developers.

Want to know what candy is? Welcome to join the candy family ~ here you will enjoy the most authentic Flutter dispelling experience ☝️