flutter.cn

Introduction to Flutter.cn Project

The Flutter.cn project is a comprehensive documentation site for the Flutter framework. This documentation site is built using Eleventy, a simple static site generator, and is hosted on Firebase, ensuring fast and reliable access to all users.

Contribution and Feedback

The Flutter.cn project actively encourages contributions and feedback from its community. Anyone encountering issues, bugs, or having improvement requests can file their concerns on the project's issue tracker or propose changes through a pull request. Minor corrections, such as text adjustments, can easily be made using the GitHub user interface. For issues pertaining to the API documentation specifically, users are directed to report these at the flutter/flutter repository, as these API docs are embedded within Flutter's source code and managed by the engineering team.

Before You Submit a PR

The team behind Flutter.cn appreciates the community's involvement in enhancing the documentation. Here are some pointers for those looking to submit a pull request (PR):

• While an issue may be tagged with a PRs welcome label, contributions on other issues are equally encouraged.
• It's advised not to run the documentation text through grammar checkers like Grammarly, as those changes may not align with the existing style guidelines.
• The project follows the Google Developer Documentation Style Guidelines, which includes avoiding the use of "i.e." or "e.g.", writing in the first person, and future tense.

How to Contribute

To make updates or improvements, contributors need to fork the repository, implement necessary changes, and then generate a pull request. For minor adjustments like style or typo fixes, building the site locally may not be necessary. If a change involves more complex modifications, such as adding/removing pages, code samples, or affecting navigation, it's recommended to build and test changes before submission.

Building the Site Locally

For contributors interested in advanced modifications, running the site locally is advised to facilitate an edit-refresh cycle and directly observe changes. Below are the steps to prepare for building the site:

1. Prerequisites:

   • Install the latest stable releases of Flutter and Node.js, as these are essential for building and developing the site.
   • Ensure both Flutter and Node.js are on your system path and up to date.

2. Cloning the Repository:

   • The repository includes submodules. Clone it using the --recurse-submodules option or update the submodules post-cloning with git submodule update --init --recursive.

3. Setting Up the Environment:

   • Install the necessary Dart dependencies using dart pub get.
   • Optionally, use pnpm, a package manager, to install npm dependencies. This can be done by running pnpm install.

4. Running the Site Locally:

   • Use the dash_site tool to validate the setup and learn available commands, then serve the site locally with ./dash_site serve.
   • View changes at http://localhost:4000 in a web browser. The port number might vary if 4000 is occupied.

5. Making Changes:

   • As modifications are made, the site typically rebuilds automatically. However, re-running the serve command may be necessary if updates do not appear.

Validating Changes

For those who have altered the code within the /examples or /tool directories, verifying conformity to site standards is important. Use the ./dash_site check-all command to ensure everything aligns with the required standards.

Optional: Deploying a Staging Site

Contributors can deploy a built version of the site to a Firebase project for staging purposes. This involves logging into Firebase, building the site using ./dash_site build, and then deploying it using firebase deploy --only hosting.

This structured approach not only optimizes collaboration but also maintains the integrity and quality of the documentation for all Flutter framework users and developers.