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>
The team had feedback during a sprint retro that the breaking change
process documentation was a bit spread out. In particular, some team
members were not clear that you need to a) update the breaking.md file
and b) add the "BREAKING CHANGE" comment to the commit description.
This PR adds both of these things are comments for awareness.
I've noticed a few instances where the team forgets to add the
"resolves" keyword (or similar "closes"/"fixes" keywords) when linking a
PR to an issue. GitHub will not link the PR with the issue and will not
close the issue on PR merge unless one of these keywords is used.
I've updated the PR template to add the "resolves" keyword so team
members don't need to worry about remembering to add it.
Removes the comments about reading the contributing guide from our pull
request template. GitHub recommends the contributing guide in a popup to
new contributors, and it also recommends it if anything has changed
recently.
Now that the PR description is used as the default commit message, the
issue a PR resolves is specified directly in the PR description.
However, the conventional-commits tool isn't smart enough to recognize
full issue URLs, only the issue number (e.g. `resolves #12345`). This PR
updates the template to nudge the description in this direction.
Now that the default commit message uses the PR description, the
conventional commit tool is getting confused when it sees other URLs and
text that looks like issues (like hex colors).
Using the `-------` separates the issue URL from the rest of the PR
description and helps the conventional commits tool generate the
changelog correctly.
Example:
https://github.com/ionic-team/ionic-framework/releases/tag/v7.0.3-nightly.20230417
`item: ios active state has correct contrast` has issue 000 as the issue
the commit closes. This is happening because I mentioned the 000 hex
color in the commit description.
* docs(issue_template): add ionic v3 for issue template
Now that v3 is officially in beta, this is needed for bug reports
* docs(pull_request_template): add ionic v3 for pull request template
