-
Notifications
You must be signed in to change notification settings - Fork 13.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore(docs): consolidate the developer resource files into a docs/ di…
…rectory (#29266) Start your review here 👉 [docs/README.md](https://github.com/ionic-team/ionic-framework/blob/FW-6107/docs/README.md) ## What is the current behavior? Documentation files with information on how to contribute, component implementations, testing, etc. are scattered throughout various folders in this repository. ## What is the new behavior? Consolidates the documentation files into a root `docs/` directory for easier discovery and organization. `/docs` tree: ``` ├── _config.yml ├── component-guide.md ├── CONTRIBUTING.md ├── README.md ├── sass-guidelines.md ├── angular │ ├── README.md │ └── testing.md ├── core │ ├── README.md │ └── testing │ ├── README.md │ ├── api.md │ ├── best-practices.md │ ├── preview-changes.md │ └── usage-instructions.md ├── react │ ├── README.md │ └── testing.md ├── react-router │ ├── README.md │ └── testing.md ├── vue │ ├── README.md │ └── testing.md └── vue-router ├── README.md └── testing.md ``` **Migrates the following:** | Previous Location | New Location | | ----------------------------------------------------------- | ----------------------------------------- | | `.github/COMPONENT-GUIDE.md` | `docs/component-guide.md` | | `.github/CONTRIBUTING.md` | `docs/CONTRIBUTING.md` | | `core/scripts/README.md` | `docs/core/testing/preview-changes.md` | | `core/src/utils/test/playwright/docs/api.md` | `docs/core/testing/api.md` | | `core/src/utils/test/playwright/docs/best-practices.md` | `docs/core/testing/best-practices.md` | | `core/src/utils/test/playwright/docs/README.md` | `docs/core/testing/README.md` | | `core/src/utils/test/playwright/docs/usage-instructions.md` | `docs/core/testing/usage-instructions.md` | | `packages/angular/test/README.md` | `docs/angular/testing.md` | | `packages/react-router/test/README.md` | `docs/react-router/testing.md` | | `packages/react/test/README.md` | `docs/react/testing.md` | | `packages/react/test/base/README.md` | `docs/react/testing.md` | | `packages/vue/test/README.md` | `docs/vue/testing.md` | **Adds the following:** | File | Description | | ----------------------------- | ----------------------------------------------------------------------- | | `docs/sass-guidelines.md` | Sass Variable guidelines taken from `ionic-framework-design-documents` | | `docs/README.md` | Entry file that should link to all other files | | `docs/_config.yml` | Config file for use with GitHub pages | | `docs/core/README.md` | Description of core, links to contributing and testing | | `docs/angular/README.md` | Description of angular, links to contributing and testing | | `docs/react/README.md` | Description of react, links to contributing and testing | | `docs/react-router/README.md` | Description of react-router, links to contributing and testing | | `docs/vue/README.md` | Description of vue, links to contributing and testing | | `docs/vue-router/README.md` | Description of vue-router, links to contributing and testing | | `docs/vue-router/testing.md` | Testing file for vue-router, populated from vue-router's main README | **Does not** add any files for `angular-server`. This is because the README is essentially empty and there is no testing in that directory. I can add blank files if we want to have something to add to later. **Does not** migrate the content of the packages' root `README.md` files. These files are used for their npm package descriptions so we should not edit them. ## Hosting Documentation We can (and should) host these files using GitHub Pages. I have duplicated them in a personal repository to see how this would look: [docs-consolidation](https://brandyscarney.github.io/docs-consolidation/). Doing so will require some formatting fixes (see [Sass Guidelines](https://brandyscarney.github.io/docs-consolidation/sass-guidelines.html#-reusable-values)) so I did not publish them now but we can easily enable GitHub pages by toggling a setting in this repository. ## Other information - Verify that no documentation files were missed in the migration - You can use these commands to search for `*.md` files in a directory: - `find core/src -type f -name "*.md" -print` - `find packages/angular -type f -name "*.md" -not -path "**/node_modules/*" -print` - I did add some redirect links in some of the existing markdown files so they might still exist for that reason - We should probably break up the contributing + component guide documentation into smaller files, such as including best practices, but I wanted to get everything in the same place first - The contributing has sections on each of the packages that we could move to that package's docs folder: https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#core --------- Co-authored-by: Maria Hutt <thetaPC@users.noreply.github.com>
- Loading branch information
1 parent
7b6c330
commit b315b0c
Showing
32 changed files
with
1,140 additions
and
382 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,44 +1,4 @@ | ||
|
|
||
| ## Build | ||
| # Core Scripts | ||
|
|
||
| ### 1. Clone ionic | ||
|
|
||
| git@github.com:ionic-team/ionic.git | ||
| cd ionic | ||
|
|
||
| ### 2. Run `npm install` | ||
|
|
||
| cd core | ||
| npm install | ||
|
|
||
|
|
||
| Notice that `@ionic/core` lives in `core`. | ||
|
|
||
| ### 3. Run `npm start` | ||
|
|
||
| Make sure you are inside the `core` directory. | ||
|
|
||
| npm start | ||
|
|
||
| With the `dev` command, Ionic components will be built with [Stencil](https://stenciljs.com/), changes to source files are watched, a local http server will startup, and http://localhost:3333/ will open in a browser. | ||
|
|
||
| ### 4. Preview | ||
|
|
||
| Navigate to http://localhost:3333/src/components/. Each component has small e2e apps found in the `test` directory, for example: http://localhost:3333/src/components/button/test/basic | ||
|
|
||
| As changes are made in an editor to source files, the e2e app will live-reload. | ||
|
|
||
| ## How to contribute | ||
|
|
||
| 1. `npm start` allows you to modify the components and have live reloading, just like another ionic app. | ||
|
|
||
| 2. When everything looks good, run `npm run validate` to verify the tests linter and production build passes. | ||
|
|
||
|
|
||
| # Deploy | ||
|
|
||
| 1. `npm run prepare.deploy` | ||
| 2. Review/update changelog | ||
| 3. Commit updates using the package name and version number as the commit message. | ||
| 4. `npm run deploy` | ||
| 5. :tada: | ||
| This file has been moved to [/docs/core/testing/preview-changes.md](/docs/core/testing/preview-changes.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,11 +1,3 @@ | ||
| # Ionic E2E Tests Guide | ||
|
|
||
| This directory contains information on how to get the most out of Ionic's E2E test infrastructure when writing tests. | ||
|
|
||
| ## Directory | ||
|
|
||
| | Directory | Description | | ||
| | - | - | | ||
| | [Usage Instructions](./usage-instructions.md) | How to run tests and update screenshots | | ||
| | [Best Practices](./best-practices.md) | Contains information on conventions to follow as well as pitfalls to avoid when writing tests | | ||
| | [API](./api.md) | Documents the custom functionality that has been built on top of Playwright | | ||
| Refer to the [Core Testing documentation](/docs/core/testing/README.md) in order to build and run the e2e tests. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| <p align="center"> | ||
| <img alt="Ionic Logo" src="https://github.com/ionic-team/ionic-framework/blob/main/.github/assets/logo.png?raw=true" width="60" /> | ||
| </p> | ||
|
|
||
| <h1 align="center"> | ||
| Ionic Framework Developer Resources | ||
| </h1> | ||
|
|
||
| <p align="center"> | ||
| This documentation includes guidelines on contributing, coding conventions, best practices, testing steps, and more. It should serve as a collective resource for all documentation related to developing Ionic Framework. | ||
| </p> | ||
|
|
||
| ## What is Ionic Framework? | ||
|
|
||
| Ionic Framework is an open source app development toolkit for building modern, fast, top-quality cross-platform native and Progressive Web Apps from a single codebase with JavaScript and the Web. | ||
|
|
||
| It is based on <a href="https://www.webcomponents.org/introduction">Web Components</a>, which enables significant performance, usability, and feature improvements alongside support for popular web frameworks like <a href="https://angular.io/">Angular</a>, <a href="https://reactjs.com/">React</a>, and <a href="https://vuejs.org/">Vue</a>. | ||
|
|
||
| ## Guides | ||
|
|
||
| | Guide | Description | | ||
| | ----------------------------------------| ---------------------------------------------------------------------------------------- | | ||
| | [Contributing](./CONTRIBUTING.md) | How to contribute including creating pull requests, commit message guidelines, and more. | | ||
| | [Component Guide](./component-guide.md) | Guidelines for implementing component states, accessibility, and more. | | ||
| | [Sass Guidelines](./sass-guidelines.md) | Outlines scenarios where Sass members and comments should be used. | | ||
|
|
||
| ## Packages | ||
|
|
||
| | Project | Package | Documentation | Guides | | ||
| | ---------------- | -------------------------------------------------------------------------- | ---------------------------------| ----------------------------------------------------------------- | | ||
| | **Core** | [`@ionic/core`](https://www.npmjs.com/package/@ionic/core) | [Readme](core/README.md) | [Testing](core/testing/README.md) | | ||
| | **Angular** | [`@ionic/angular`](https://www.npmjs.com/package/@ionic/angular) | [Readme](angular/README.md) | [Testing](angular/testing.md) | | ||
| | **React** | [`@ionic/react`](https://www.npmjs.com/package/@ionic/react) | [Readme](react/README.md) | [Testing](react/testing.md) | | ||
| | **React Router** | [`@ionic/react-router`](https://www.npmjs.com/package/@ionic/react-router) | [Readme](react-router/README.md) | [Testing](react-router/testing.md) | | ||
| | **Vue** | [`@ionic/vue`](https://www.npmjs.com/package/@ionic/vue) | [Readme](vue/README.md) | [Testing](vue/testing.md) | | ||
| | **Vue Router** | [`@ionic/vue-router`](https://www.npmjs.com/package/@ionic/vue-router) | [Readme](vue-router/README.md) | [Testing](vue-router/testing.md) | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| name: Ionic Framework | ||
| include: [ CONTRIBUTING.md ] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # Ionic Angular | ||
|
|
||
| The [@ionic/angular](https://www.npmjs.com/package/@ionic/angular) package builds on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components. | ||
|
|
||
| ## Contributing | ||
|
|
||
| See our [Contributing Guide](/docs/CONTRIBUTING.md). | ||
|
|
||
| ## Testing | ||
|
|
||
| Refer to the [Angular Testing documentation](./testing.md) for testing the Angular package. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,118 @@ | ||
| # Angular Testing | ||
|
|
||
| Ionic Framework supports multiple versions of Angular. As a result, we need to verify that Ionic works correctly with each of these Angular versions. | ||
|
|
||
| ## Syncing Local Changes | ||
|
|
||
| The Angular test app supports syncing your locally built changes for validation. | ||
|
|
||
| 1. Build the `core` and `packages/angular` directories using `npm run build`. | ||
| 2. [Build the Angular test app](#test-app-build-structure). | ||
| 3. Navigate to the built test app directory (e.g. `packages/angular/test/build/ng14`). | ||
| 4. Install dependencies using `npm install`. | ||
| 5. Sync your local changes using `npm run sync`. | ||
|
|
||
| From here you can either build the application or start a local dev server. When re-syncing changes, you will need to [wipe or disable the application cache](#application-cache). | ||
|
|
||
| ## Application Cache | ||
|
|
||
| Angular CLI creates a cache of several files on disk by default in the `.angular` directory. This decreases the time taken to build the test application. However, the cache makes it difficult to quickly sync and check local changes of Ionic. As a result, the `.angular` cache is disabled by default in the test app projects. | ||
|
|
||
| See https://angular.io/cli/cache for more information. | ||
|
|
||
| ### Disable Cache | ||
|
|
||
| ```shell | ||
| ng cache disable | ||
| ``` | ||
|
|
||
| > [!NOTE] | ||
| > You may need to manually remove the `.angular` directory once after running this command. | ||
| ### Enable Cache | ||
|
|
||
| ```shell | ||
| ng cache enable | ||
| ``` | ||
|
|
||
| > [!NOTE] | ||
| > You will need to delete the `.angular` cache and restart the dev server every time you want to sync local changes of Ionic. | ||
| ## Test App Build Structure | ||
|
|
||
| > [!NOTE] | ||
| > Please confirm your current directory as `packages/angular/test` before proceeding with any of the following commands. | ||
| Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application. | ||
|
|
||
| **apps** - This directory contains partial applications for each version of Angular we want to test. Typically these directories contain new `package.json` files, `angular.json` files, and more. If you have code that is specific to a particular version of Angular, put it in this directory. | ||
|
|
||
| **base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory. | ||
|
|
||
| **build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git. | ||
|
|
||
| **build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory. | ||
|
|
||
| Usage: | ||
|
|
||
| ```shell | ||
| # Build a test app using apps/ng14 as a reference | ||
| ./build.sh ng14 | ||
| ``` | ||
|
|
||
| ## How to modify test apps | ||
|
|
||
| To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version. | ||
|
|
||
| If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.spec.ts` in `apps/ng14`, make sure you place the file in `apps/ng14/e2e/src/test.spec.ts`. | ||
|
|
||
| ### Version-specific tests | ||
|
|
||
| If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. | ||
|
|
||
| ### Testing Lazy Loaded Ionic Components | ||
|
|
||
| Tests for lazy loaded Ionic UI components should only be added under the `/lazy` route. This ensures the `IonicModule` is added. | ||
|
|
||
| ### Testing Standalone Ionic Components | ||
|
|
||
| Tests for standalone Ionic UI components should only be added under the `/standalone` route. This allows for an isolated environment where the lazy loaded `IonicModule` is not initialized. The standalone components use Stencil's custom element bundle instead of the lazy loaded bundle. If `IonicModule` is initialized then the Stencil components will fall back to using the lazy loaded implementation instead of the custom elements bundle implementation. | ||
|
|
||
| ## Adding New Test Apps | ||
|
|
||
| As we add support for new versions of Angular, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps: | ||
|
|
||
| 1. Navigate to the built app for the most recent version of Angular that Ionic tests. | ||
| 2. Update the application by following the steps on https://update.angular.io/. | ||
| 3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, `angular.json`, etc). | ||
| 4. Copy the changed files to a new directory in `apps`. | ||
| 5. Add a new entry to the matrix for `test-core-angular` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs. | ||
| 6. Commit these changes and push. | ||
|
|
||
| Example: | ||
|
|
||
| In this example, we are going to add the Angular 14 test app. | ||
|
|
||
| 1. Build the Angular 13 test app using `./build.sh ng13`. | ||
| 2. Navigate to `build/ng13`. | ||
| 3. Perform the upgrade steps on https://update.angular.io/. The "From" field should say "13.0" and the "To" field should say "14.0". | ||
|
|
||
| Note: You may encounter some other peer dependency issues not covered by the Angular Upgrade Guide. These peer dependency issues can be resolved manually by updating the installed version of each dependency. | ||
|
|
||
| 4. Observe that the output of the Angular upgrade indicates that the following files were modified: | ||
|
|
||
| `angular.json` | ||
| `package-lock.json` | ||
| `package.json` | ||
| `tsconfig.json` | ||
| `src/app/form/form.component.ts` | ||
| `src/app/modal-example/modal-example.component.ts` | ||
|
|
||
| 5. Create a directory in `apps` named `ng14`. | ||
| 6. Copy the modified files to the `apps/ng14` directory. | ||
| 7. Open `./github/workflows/build.yml` and find the `test-angular-e2e` job. | ||
| 8. Find the `apps` field under `matrix`. | ||
| 9. Add "ng14" to the `apps` field. | ||
| 10. Open `./github/workflows/stencil-nightly.yml` and find the `test-angular-e2e` job. | ||
| 11. Repeat steps 8 and 9. | ||
| 12. Commit these changes and push. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # Ionic Core | ||
|
|
||
| The [@ionic/core](https://www.npmjs.com/package/@ionic/core) package contains the Web Components that make up the reusable UI building blocks of Ionic Framework. These components are designed to be used in traditional frontend view libraries/frameworks (such as React, Angular, or Vue), or on their own through traditional JavaScript in the browser. | ||
|
|
||
| ## Contributing | ||
|
|
||
| See our [Contributing Guide](/docs/CONTRIBUTING.md). | ||
|
|
||
| ## Testing | ||
|
|
||
| Refer to the [Core Testing documentation](./testing/README.md) for testing the Core package. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
|
|
||
| # Core Testing | ||
|
|
||
| ## Directory | ||
|
|
||
| | Directory | Description | | ||
| | --------------------------------------------- | --------------------------------------------------------------------------------------------- | | ||
| | [Preview Changes](./preview-changes.md) | Steps on building core and previewing changes | | ||
| | [Usage Instructions](./usage-instructions.md) | How to run tests and update screenshots | | ||
| | [Best Practices](./best-practices.md) | Contains information on conventions to follow as well as pitfalls to avoid when writing tests | | ||
| | [API](./api.md) | Documents the custom functionality that has been built on top of Playwright | | ||
|
|
||
|
|
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| # Preview Changes | ||
|
|
||
| ## Build | ||
|
|
||
| ### 1. Clone ionic | ||
|
|
||
| git clone https://github.com/ionic-team/ionic-framework.git | ||
| cd ionic-framework | ||
|
|
||
| ### 2. Run `npm install` | ||
|
|
||
| cd core | ||
| npm install | ||
|
|
||
| Notice that `@ionic/core` lives in `core`. | ||
|
|
||
| ### 3. Run `npm start` | ||
|
|
||
| Make sure you are inside the `core` directory. | ||
|
|
||
| npm start | ||
|
|
||
| With the `start` command, Ionic components will be built with [Stencil](https://stenciljs.com/), changes to source files are watched, a local http server will startup, and [http://localhost:3333/](http://localhost:3333/) will open in a browser. | ||
|
|
||
| ### 4. Preview | ||
|
|
||
| Navigate to [http://localhost:3333/src/components/](http://localhost:3333/src/components/). Each component has small e2e apps found in the `test` directory, for example: [http://localhost:3333/src/components/button/test/basic](http://localhost:3333/src/components/button/test/basic) | ||
|
|
||
| As changes are made in an editor to source files, the e2e app will live-reload. |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # Ionic React Router | ||
|
|
||
| The [@ionic/react-router](https://www.npmjs.com/package/@ionic/react-router) package is the routing integration for [@ionic/react](https://www.npmjs.com/package/@ionic/react). It uses the [React Router](https://github.com/remix-run/react-router) library beneath the surface. | ||
|
|
||
| ## Contributing | ||
|
|
||
| See our [Contributing Guide](/docs/CONTRIBUTING.md). | ||
|
|
||
| ## Testing | ||
|
|
||
| Refer to the [React Router Testing documentation](./testing.md) for testing the React Router package. |
Oops, something went wrong.