diff --git a/.dockerignore b/.dockerignore index ac1848431c..d548f27043 100644 --- a/.dockerignore +++ b/.dockerignore @@ -2,8 +2,6 @@ .gitignore AUTHORS CONTRIBUTING.md -docker-compose.yml LICENSE node_modules/ README.md -flutter/ diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 1b43c8d928..9847db1627 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -17,7 +17,7 @@ env: jobs: test: - name: Check excerpts and run tests + name: Analyze and test code examples runs-on: ubuntu-latest if: github.repository == 'cfug/flutter.cn' strategy: @@ -36,10 +36,36 @@ jobs: submodules: recursive - name: Move docs run: make move-docs - - name: Test - env: - FLUTTER_BUILD_BRANCH: ${{ matrix.branch }} - run: make test + - uses: subosito/flutter-action@2783a3f08e1baf891508463f8c6653c258246225 + with: + channel: ${{ matrix.branch }} + - name: Fetch Dart dependencies + run: dart pub get + - name: Check Dart code formatting + run: dart run flutter_site format-dart --check + continue-on-error: ${{ matrix.experimental }} + - name: Analyze Dart code + run: dart run flutter_site analyze-dart + continue-on-error: ${{ matrix.experimental }} + - name: Run Dart tests + run: dart run flutter_site test-dart + continue-on-error: ${{ matrix.experimental }} + + excerpts: + name: Check if code excerpts are up to date + runs-on: ubuntu-latest + if: github.repository == 'cfug/flutter.cn' + steps: + - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 + with: + submodules: recursive + - uses: dart-lang/setup-dart@fedb1266e91cf51be2fdb382869461a434b920a3 + with: + sdk: stable + - name: Fetch Dart dependencies + run: dart pub get + - name: Check if excerpts are up to date + run: dart run flutter_site refresh-excerpts --fail-on-update continue-on-error: ${{ matrix.experimental }} linkcheck: @@ -53,20 +79,41 @@ jobs: submodules: recursive - name: Build site and check links run: make build BUILD_CONFIGS=_config.yml,_config_stage.yml -# - name: Install Node for Firebase install -# uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 -# with: -# node-version: ${{ env.NODE_VERSION }} -# - name: Install Firebase CLI -# run: npm install -g firebase-tools@13.0.2 + - name: Install Node for Firebase install + uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 + with: + node-version: ${{ env.NODE_VERSION }} + - name: Install Firebase CLI + run: npm install -g firebase-tools@13.0.2 + - uses: dart-lang/setup-dart@fedb1266e91cf51be2fdb382869461a434b920a3 + with: + sdk: stable + - name: Fetch Dart dependencies + run: dart pub get + - name: Check for broken Markdown link references + run: dart run flutter_site check-link-references + - name: Check for broken internal links + run: dart run flutter_site check-links + + firebase-validate: + name: Validate Firebase configuration + runs-on: ubuntu-latest + if: github.repository == 'cfug/flutter.cn' + steps: + - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 + with: + submodules: recursive - uses: dart-lang/setup-dart@fedb1266e91cf51be2fdb382869461a434b920a3 with: sdk: stable - - run: tool/check-links.sh + - name: Fetch Dart dependencies + run: dart pub get + - name: Validate the firebase.json file + run: dart run flutter_site verify-firebase-json deploy: name: Deploy to production - needs: [test, linkcheck] + needs: [test, excerpts, linkcheck, firebase-validate] runs-on: ubuntu-latest if: | github.event_name == 'push' @@ -78,18 +125,6 @@ jobs: submodules: recursive - name: Build site run: make build -# - name: Install Node for Firebase install -# uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 -# with: -# node-version: ${{ env.NODE_VERSION }} -# - name: Install Firebase CLI -# run: npm install -g firebase-tools@13.0.2 -# - uses: dart-lang/setup-dart@fedb1266e91cf51be2fdb382869461a434b920a3 -# with: -# sdk: stable -# - run: tool/check-links.sh -# - name: Deploy to Firebase hosting -# run: make deploy # TODO(drewroengoogle) Run deploy on Cloud Build. - name: Deploy CN run: make deploy env: diff --git a/.gitignore b/.gitignore index 494fd9bee4..14507c43ed 100644 --- a/.gitignore +++ b/.gitignore @@ -10,7 +10,7 @@ _site *.swp build node_modules -flutter/ +./flutter/ # Dart and Flutter, build related .dart_tool diff --git a/Dockerfile b/Dockerfile index f1707fcd3f..4ae873f610 100644 --- a/Dockerfile +++ b/Dockerfile @@ -15,7 +15,6 @@ RUN apt-get update && apt-get install -yq --no-install-recommends \ build-essential \ ca-certificates \ curl \ - diffutils \ git \ gnupg \ lsof \ @@ -27,39 +26,8 @@ RUN apt-get update && apt-get install -yq --no-install-recommends \ WORKDIR /app - - -# ============== INSTALL FLUTTER ============== -FROM base AS flutter - -COPY ./site-shared ./site-shared -COPY pubspec.yaml ./ - -ARG FLUTTER_BUILD_BRANCH=stable -ENV FLUTTER_BUILD_BRANCH=$FLUTTER_BUILD_BRANCH -ENV FLUTTER_ROOT=flutter -ENV FLUTTER_BIN=flutter/bin -ENV PATH="/flutter/bin:$PATH" - -RUN git clone --branch $FLUTTER_BUILD_BRANCH --single-branch --filter=tree:0 https://github.com/flutter/flutter /flutter/ -VOLUME /flutter - -#ENV PUB_HOSTED_URL="https://pub.flutter-io.cn" -#ENV FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn" - -# Set up Flutter -# NOTE You will get a warning "Woah! You appear to be trying to run flutter as root." -# and this is to be disregarded since this image is never deployed to production. -RUN flutter doctor -RUN flutter config --no-analytics \ - && flutter config --no-cli-animations \ - && flutter --version -RUN dart pub get - - - # ============== NODEJS INTSALL ============== -FROM flutter AS node +FROM base AS node RUN mkdir -p /etc/apt/keyrings \ && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \ @@ -68,51 +36,6 @@ RUN mkdir -p /etc/apt/keyrings \ && apt-get install nodejs -yq \ && npm install -g npm # Ensure latest npm - -# ============== FLUTTER CODE TESTS ============== -FROM flutter AS tests - -COPY ./ ./ - -# Only test the code here, checking links is purely for site deployment -ENTRYPOINT ["tool/test.sh"] - - -# ============== DEV / JEKYLL SETUP ============== -FROM node AS dev - -#RUN gem sources --add https://mirrors.tuna.tsinghua.edu.cn/rubygems/ --remove https://rubygems.org/ -#RUN bundle config mirror.https://rubygems.org https://mirrors.tuna.tsinghua.edu.cn/rubygems - -ENV JEKYLL_ENV=development -ENV RUBY_YJIT_ENABLE=1 -RUN gem install bundler -COPY Gemfile Gemfile.lock ./ -RUN bundle config set force_ruby_platform true -RUN bundle install - -# Install Node deps -ENV NODE_ENV=development -COPY package.json package-lock.json ./ -RUN npm ci - -COPY ./ ./ - -# Jekyl ports -EXPOSE 35730 -EXPOSE 4002 - -# Firebase emulator port -# Airplay runs on :5000 by default now -EXPOSE 5502 - -RUN tool/move_docs.sh - -# ============== BUILD DEV JEKYLL SITE ============== -FROM dev as dev-build - -RUN tool/move_docs.sh; tool/translator/build.sh - # ============== BUILD PROD JEKYLL SITE ============== FROM node AS build @@ -129,7 +52,7 @@ RUN npm ci COPY ./ ./ -# RUN echo $'User-agent: *\nAllow: /' > src/robots.txt +# RUN echo 'User-agent: *\nDisallow:\n\nSitemap: https://docs.flutter.dev/sitemap.xml' > src/robots.txt ARG BUILD_CONFIGS=_config.yml ENV BUILD_CONFIGS=$BUILD_CONFIGS diff --git a/Gemfile.lock b/Gemfile.lock index 0a322ce4ef..1f19a727b6 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,7 +1,7 @@ GEM remote: https://rubygems.org/ specs: - activesupport (7.1.3) + activesupport (7.1.3.2) base64 bigdecimal concurrent-ruby (~> 1.0, >= 1.0.2) @@ -70,7 +70,7 @@ GEM rb-inotify (~> 0.9, >= 0.9.10) mercenary (0.4.0) mini_portile2 (2.8.5) - minitest (5.21.2) + minitest (5.22.2) mutex_m (0.2.0) nokogiri (1.16.2) mini_portile2 (~> 2.8.2) diff --git a/Makefile b/Makefile index dd963c0609..bef289e9aa 100644 --- a/Makefile +++ b/Makefile @@ -2,9 +2,7 @@ -include .env -all: gen-env up down debug shell setup serve emulate test debug-tests \ - stop-tests build-image build debug-build \ - deploy stage-channel stage-local clean reinstall purge +all: build clean .DEFAULT_GOAL := up .PHONY: all @@ -13,121 +11,9 @@ BUILD_COMMIT := $(shell git rev-parse --short HEAD) BUILD_CONFIGS ?= _config.yml BUILD_NAME = tmpbuild BUILD_TAG = "fltbuild:${BUILD_COMMIT}" -FIREBASE_ALIAS ?= default -FLUTTER_BUILD_BRANCH ?= stable -JEKYLL_SITE_HOST ?= 0.0.0.0 -JEKYLL_SITE_PORT ?= 4002 -STAGE_NAME ?= docs - - -# =================== Development Commands ================== - -# Generate .env file with defaults -# The .env file is used to store local secrets and settings -# NOTE that using a `FIREBASE_TOKEN` is optional and not required. -# If you have generated a token via `firebase login:ci` and it is -# set in your `.env` file, it will be used for deployment. Otherwise, -# the command will use the manual setup described above. -# Usage: `make genenv` -.env: - touch $@ -genenv: .env - @echo "FLUTTER_BUILD_BRANCH=stable" >> $< - @echo "FIREBASE_ALIAS=default" >> $< - @echo "FIREBASE_TOKEN=" >> $< - - -# Start the dev container and serve the Jekyll site. If the -# site is not yet built, this will run build automatically -up: - docker-compose up site - -# Bring down the running dev container -down: - docker-compose down - -# Run the dev container and enter shell for debugging -debug: - docker-compose run --rm site bash - -# Enter the shell of the *running* dev container -shell: - docker-compose exec site bash - -# Build the dev container from scratch. -# Runs packages installs a second time for both Gems and NPM to -# overcome inconsistent bugs with missing packages at runtime. -setup: - make clean - docker-compose build --no-cache site - docker-compose run --rm site npm install - docker-compose run --rm site bundle config set force_ruby_platform true - docker-compose run --rm site bundle install - -# Serve the Jekyll site with livereload and incremental builds -# NOTE this is run inside of the container on `make up` -serve: - bundle exec jekyll serve \ - --host ${JEKYLL_SITE_HOST} \ - --port ${JEKYLL_SITE_PORT} \ - --config _config.yml,_config_dev.yml \ - --livereload \ - --livereload_port 37530 \ - --incremental \ - --trace \ - --skip-initial-build - -# Test hosting locally with FB emulator -emulate: - firebase emulators:start --only hosting --project ${FIREBASE_ALIAS} - - -# =================== Build / Test / Deploy Commands ================== - -# Run all tests that would be run inside the container for the -# given target channel on the GitHub action `test` job. -# WARNING this can take a while to run! -# Usage: `FLUTTER_BUILD_BRANCH= make test` -test: - @echo "::group::Setting up container" - DOCKER_BUILDKIT=1 docker build --rm \ - --target tests \ - -t flt-test \ - --build-arg FLUTTER_BUILD_BRANCH=${FLUTTER_BUILD_BRANCH} . - @echo "::endgroup::" - docker run --rm --name flt-tests -t flt-test - -# Stop long running tests -# Usage `make stop-tests` -stop-tests: - docker stop flt-tests - -# Allows for firing up a shell with a regular build and -# running shell scripts manually to test the build. -# Usage `make debug-tests` -debug-tests: - DOCKER_BUILDKIT=1 docker build --rm --target flutter -t flt-test . - docker run --rm -it -v ${PWD}:/app flt-test bash - docker rmi --name flt-tests -f flt-test - -# Build the production site -# NOTE important to disable tests with the local build as -# those will be run on the Github action. -# Usage: `make build-image` -build-image: - DOCKER_BUILDKIT=1 docker build --rm --no-cache --target build \ - --build-arg BUILD_CONFIGS=${BUILD_CONFIGS} -t ${BUILD_TAG} . - -# Hit the shell on the built site imag -# This requires that a build:commit image has been built -# Usage: `make debug-build` -debug-build: - docker run --rm -it -v ${PWD}:/app ${BUILD_TAG} bash # Build the production image and copy site build to local. -# This will reset and also clean up after finished. -# NOTE important to disable tests with the local build as -# those will be run on the GitHub action. +# This will reset and also clean up after finished. # Usage: `make build` build: make clean @@ -138,6 +24,10 @@ build: docker stop ${BUILD_NAME} docker rmi -f ${BUILD_TAG} +# Clean all caches, and test/build files +clean: + rm -rf _site .jekyll* src/.jekyll* *.log tmp .dart_tool + # Deploy the Firebase hosting site from local. # NOTE that if you have a FIREBASE_TOKEN exported or # in your local `.env` file, it will be used. This style @@ -146,6 +36,11 @@ build: deploy: bash tool/translator/deploy-cn.sh +# Move around docs in order to customize path orders +move-docs: + bash tool/move_docs.sh + + stage-local: make clean DOCKER_BUILDKIT=1 docker build --rm --no-cache --target build \ @@ -154,24 +49,3 @@ stage-local: docker cp ${BUILD_NAME}:/app/_site _site docker stop ${BUILD_NAME} docker rmi -f ${BUILD_TAG} - -# =================== Utility Commands ================== - -# Clean all caches, and test/build files -clean: - rm -rf _site .jekyll* src/.jekyll* *.log tmp .dart_tool - -# Helpful to reinstall all Ruby packages from inside container -reinstall: - rm -f Gemfile.lock - bundle install --redownload - -# Purge all running containers and remove the image -purge: - docker-compose down - docker rm -f $(docker ps -aq) - docker rmi flt-dev - -# Move around docs in order to customize path orders -move-docs: - bash tool/move_docs.sh diff --git a/README.md b/README.md index a6552c2438..a745605804 100644 --- a/README.md +++ b/README.md @@ -16,18 +16,9 @@ * [Issues, bugs, and requests](#issues-bugs-and-requests) * [Before you submit a PR](#before-you-submit-a-pr) * [Before you build this site](#before-you-build-this-site) - - [1. Get the prerequisites](#1-get-the-prerequisites) - - [2. Clone this repo _and_ its submodules][] -* [Setting up your local environment and serving changes][] * [Creating and/or editing DartPad example code](#creating-andor-editing-dartpad-example-code) - - [DartPad example code in GitHub gists](#dartpad-example-code-in-github-gists) - - [DartPad example code in this repo](#dartpad-example-code-in-this-repo) -* [Deploying to a staging site](#deploying-to-a-staging-site) * [Writing for flutter.dev](#writing-for-flutterdev) -[2. Clone this repo _and_ its submodules]: #2-clone-this-repo-and-its-submodules -[Setting up your local environment and serving changes]: #setting-up-your-local-environment-and-serving-changes - ## Issues, bugs, and requests We welcome contributions and feedback on our website. @@ -76,26 +67,14 @@ But here are a few notes to keep in mind before you submit a PR: For changes beyond simple text and CSS tweaks, we recommend building the site. -### 1. Get the prerequisites - -Install the following tools, if you don't have them already: - -- **bash**, the Bourne shell
- These instructions assume you're using `bash`, - and setup might not work if you use another shell. -- **GNU Make**
- On Windows the easiest way to install Make is `choco install make`. - Other options include using a - [subsystem](https://docs.microsoft.com/en-us/windows/wsl/install-win10). -- **Docker**. - We use Docker for local dev, tests, and building the site. - Install it from https://docs.docker.com/get-docker/. -- **Firebase CLI**, for hosting the site locally. - One way to get this is to run `npm install -g firebase-tools`. - For full setup details, read the - [Firebase CLI documentation](https://firebase.google.com/docs/cli). +> [!WARNING] +> Support for building the site locally has temporarily been removed. +> This README will be updated with the new building details soon. +> +> Until then, please rely on automatic staging in pull requests. +> Thanks for your patience! -### 2. Clone this repo _and_ its submodules +### Clone this repo _and_ its submodules > **Note:** This repo has git _submodules_, > which affects how you clone it. @@ -114,6 +93,7 @@ _choose one_ of the following submodule-cloning techniques: - Clone the repo and its submodule at the same using the `--recurse-submodules` option: +- ```bash $ git clone --recurse-submodules https://github.com//website.git ``` @@ -121,7 +101,8 @@ _choose one_ of the following submodule-cloning techniques: OR - If you've already cloned the repo without its submodule, - then run this command from the repo root:
+ then run this command from the repo root: + ```bash $ git submodule update --init --recursive ``` @@ -133,68 +114,6 @@ _choose one_ of the following submodule-cloning techniques: > $ git pull; git submodule update --init --recursive > ``` -## Setting up your local environment and serving changes - -1. _Optional:_ After cloning the repo and its submodules, - create a branch for your changes: - ```bash - $ git checkout -b - ``` - -1. If the Docker Desktop application isn't already running, - start it. Look at its status icon: - if it has an exclamation point (`!`), - then update Docker Desktop. - -1. Run the initial setup command: - ```bash - $ make setup - ``` - -1. Serve the site locally (via `docker-compose`): - ```bash - $ make up - ``` - The site is generated, - and then the development server runs in the Docker container, - with the generated `_site` directory visible locally. - -1. View your changes in the browser by navigating to `http://localhost:4002`. - > **Note:** Unless you're editing files under `site-shared`, - > you can safely ignore - > `ERROR: directory is already being watched` messages. - > For details, see [#1363](https://github.com/flutter/website/issues/1363). - -1. Make your changes. - The files are updated, - and your browser view should update to reflect the changes. - You can either edit files locally or use an editor like `vim` - directly in a shell in the container. - To start a container shell, run `docker-compose exec site bash`. - - > **Tip:** If you aren't seeing the changes you expect, - > restart the server and rebuild the site from scratch: - > ```bash - > $ make down && make clean && make up - > ``` - > In some rare cases you might want to force all running containers down: - > ```bash - > $ docker rm -f $(docker ps -aq) - > ``` - -1. Commit your changes to the branch and submit your PR. - -1. When you've finished developing, shut down the Docker container: - ```bash - $ make down - ``` - -> **Tip:** To find additional commands, read the [`Makefile`][]. -> For example, if you need to debug the Docker infrastructure, -> you can run `make debug`. - -[`Makefile`]: https://github.com/flutter/website/blob/main/Makefile - ## Creating and/or editing DartPad example code Most of the code used to create [DartPad][] examples is hosted on GitHub. @@ -223,81 +142,19 @@ For detailed instructions on how to use this approach to DartPad examples, see the [DartPad embedding guide][]. [DartPad embedding guide]: https://github.com/dart-lang/dart-pad/wiki/Embedding-Guide - - -### DartPad example code in this repo - -Some DartPad example code remains in this repo: -- `src/_packages/dartpad_picker/web/dartpad_picker_main.dart` - -This code must be manually compiled, -which also regenerates the associated JavaScript file in `src/assets/js`: -```bash -$ cd src/_packages/dartpad_picker -$ ./compile.sh -``` - - -## Deploying to a staging site - -You can deploy your local edits to a personal staging site as follows. - -1. If you don't already have a Firebase project, - navigate to the - [Firebase Console](https://console.firebase.google.com) - and create your own Firebase project (for example, `my-foo`). - -1. In a separate `bash` shell, change to the repo directory - and initialize Firebase: - - ```bash - $ npx firebase init - ``` - -1. If you created a new project, add it using the - [`firebase use` command][]: - - ```bash - $ npx firebase use --add - ? Which project do you want to add?