diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000000..b7ae96035b --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,354 @@ +## In this topic + ### 1. [Writing an article](#writing-an-article) + ### 2. [Topic structure](#topic-structure) + ### 3. [Writing a Styling section for article](#styling-section) + ### 4. [Workflow](#workflow) + ### 5. [Environment variables and template tokens](#environment-variables) + ### 6. [Sample / Code View Configuration](#code-view-configuration) + ### 7. [PlatformBlock usage](#platform-block) + ### 8. [ApiLink usage](#api-link) + ### 9. [Creating shared help topics](#creating-shared-help-topics) + ### 10. [Updating of Data Visualization related topics](#updating-of-data-visualization-related-topics) + ### 11. [Adding of images](#adding-of-images-in-the-topic) + +# Writing an article + +When writing an article about a specific component, it is important to have a plan that you stick to. This will improve the overall cohesion of the text, making it more structured and clear for the reader. + +There are a few questions one can ask, when charting such plan. + +### 1. What is this article about (objective)? + + a. List required previous knowledge to better understand the concept of the topic. For instance, if the article is about a directive feature, put references to the ng directives in the beginning of the article. + + b. Identify common use cases. Where would said component/directive be used in most often. Try to outline samples around said use cases. + +### 2. What are the prerequisites to using said component/directive?\*\* Does it depend on other components, or can it be used on its own? + +### 3. How does one get started with using said component/directive? + +### 4. Identify the most important feature(s) of a component/directive. + + Why was a feature implemented? What problem does it solve? How important is that feature for the overall weight of the component? Can this component exist without the feature and still be perceived useful? Rank features by importance and write about the most important ones. + +### 5. What are some common gotchas about a component/directive’s feature? + + Does the feature require any previous knowledge? If yes, then refer the user to it. + +### 6. Can we identify some problems that may occur when using said component/directive? + + If yes, we can anticipate questions and have a troubleshooting section where we outline such issues and how to solve them. + +### 7. Do we have a summary of the article and component APIs? + + The MDX topics use the `` JSX component in place of plain markdown links to API docs. Any component class, interface, or member mentioned in the article should be linked using ``. At the end of the article, list the primary types via `` under an `## API References` heading. The component's `mentionedTypes` frontmatter field should list all types referenced in the article — this drives the auto-generated API reference grid. + + Example frontmatter: +```yaml +mentionedTypes: ["Grid", "Column", "GridToolbar"] +``` + + Example inline API links in prose: +```mdx +The supports row virtualization by default. + +Set the property to `true` to enable sorting. +``` + + Example `## API References` section at the end of the article: +```mdx +## API References + + + +``` + + See the [ApiLink usage](#api-link) section for the full syntax reference. + +### 8. Where does one find further help related to the topic of the article? + +# Topic structure + +The purpose of this section is to present what the structure of the topic should be and the arrangement of the main elements in it. + +### 1. The first title of the page should be with `

` tag (`#` Page Title) and it won't appear on the submenu on the right. + +### 2. Every main title should be with `

` tag (`##` Main Title). + +### 3. Using nested titles. +Minor titles related to the main titles can be used with `

`(`###`) or `

` (`####`). +Note: when `

` (`####`) is used the title won't appear on the submenu on the right. + +# Writing a Styling section for article + +The main purpose of the Styling section is to provide simple examples on how to style most common parts of the UI (let's say styling for alternate rows in the grid), copy/paste the code in any sample and see it working. In order to write content that fulfills the purpose, follow the steps below: + +### 1. Give the content an `

` Section header, so that it appears on the submenu on the right. +### 2. Start the content with the example of adding the theming index file. +### 3. Provide the simplest styling example, which is to extend the default theme for the corresponding feature/component. For example, when styling the paginator UI, the `igx-grid-paginator-theme` needs to be extended: + +```scss +$dark-grid-paginator: grid-paginator-theme( + $text-color: #F4D45C, + $background-color: #575757, + $border-color: #292826 +); +``` + +### 4. If other elements in the feature UI are styled by another theme, add example for that theme too. For example - the buttons in the paginator UI require that a new theme for buttons is created. +### 5. If a theme provides a ton of parameters for styling, choose those that you decide would be the most common. You may state in one sentence what each property controls, and provide a link to the theme under the SASS API. +### 6. Provide the last step, which is to include the component mixin, along with two notes – the first one for scoping any mixin if needed, and the second note about penetrating the `ViewEncapsulation`, along with example on how to overcome the encapsulation. +### 7. Add an iframe with an example, along with a Stackblitz button +### 8. Examples on styling with `igx-color`, `palettes` and `schemas` are not necessary, but you may add a link to Theming engine topics as they are quite detailed. +### 9. When adding a section for a certain grid feature, add it for the `igxHierarchicalGrid` and `igxTreeGrid` as well. + + +# Workflow + +When working on an issue for the Ignite UI for Angular DocFX Site Builder, you need to be aware of and to follow a correct status workflow. We have created a number of status labels in order to communicate well what the current status of a single issue/pull request is. The statuses are as follows: + +## Development - applicable to issues and pull requests +1. `status: in-review` this is the initial status of an issue. If the label is not placed, go ahead and place it. +2. `status: in-development` this is the status once you start working on an issue. Assign the issue to yourself if it hasn't been assigned already and remove the previous status and assign it an in development status. +3. `status: by-design` this is the status of an issue that has been reviewed and has been determined that the current design of the feature is such that the issue describes the correct behavior as incorrect. Remove other statuses and place this status if you've reviewed the issue. +4. `status: third-party-issue` this is the status of an issue that has been reviewed, has been determined to be an issue, but the root case is not in the Ignite UI for Angular code. Example would be browser specific bugs caused by the particular browser's rendering or JavaScript engines, or an issue with the Angular framework. Remove other statuses and place only this one if you're the one performing the investigation. +5. `status: not-to-fix` this is the status of issues that derive from our code, but have been decided to leave as is. This is done when fixes require general design and/or architecture changes and are very risky. +6. `status: already-fixed` this status indicates that the issue is already fixed in the source code. When setting this status assign the person that logged the issue so that he can verify the issue is fixed in the respective development branch. Remove other statuses and place this status if you've reviewed the issue. +7. `status: cannot-reproduce` this status indicates that you cannot reproduce the issue in the source code. A reason may be because the issue is already fixed. When setting this status assign the person that logged the issue so that he can respond with more details on how to reproduce it. +8. `status: not a bug` this is the status of an issue that you reviewed and concluded that it's not a bug. You should comment explaining the reasons why you think the issue is not a bug. +9. `status: resolved` this is the status of an issue that has been fixed and there are active pull requests related to it. + +Example status workflows: + +`status: in-review` => `status: in-development` => `status: resolved` (PR is created) + +`status: in-review` => `status: by-design` (Issue can be closed) + +`status: in-review` => `status: third-party-issue` (Issue can be closed) + +`status: in-review` => `status: not-to-fix` (Issue can be closed) + +> Note: In most cases the development will be related to new topics creation or updating of existing one. Keep in mind that **for each newly added topic a corresponding entry must be added to the platform sidebar configuration** so it appears in the navigation. It is recommended an `Additional references` section to be added at the end of each topic. + +## Testing - applicable to pull requests +1. `status: awaiting-test` this is the initial status of pull requests. If you're performing the pull request, please place this status on it. Pull requests are accepted if and only if all status checks pass, review is performed, and the pull request has been tested and contains `status: verified`. +2. `status: in-test` place this status once you pick up the pull request for testing. +3. `status: verified` place this status once you've tested the pull request, have verified that the issue is fixed, and have included all necessary automated tests for the issue. +4. `status: not-fixed` place this status once you've tested the pull request and you are still able to reproduce the issue it's attempting to fix. Then assign the developer back on the pull request. + +Example status workflows: + +`status: awaiting-test` => `status: in-test` => `status: verified` (PR can be merged if all prerequisites are met) + +`status: awaiting-test` => `status: in-test` => `status: not-fixed` => `status: in-development` => `status: awaiting-test` + +> Note: When you are assigned to test a PR related to new topic creation or updating an existing one: +1. Check the build result. +2. Be sure that `Writing an article` guidance is respected. +3. Check whether the embed sample is working. +4. Code views are working as well +5. Each hyperlink is working properly. +6. Table of content is correct. + +> Note: Testing a PR from Angular Samples (when new sample is added) with combination of PR related to topic update (or when new topic is added). +Open both repositories and perform `npm start`. This will start both projects and you will see the embed sample in your topic under `localhost`. + +## Localization - applicable to issues and pull requests +Ensure that whenever a change is made to the text content the appropriate status is set: +1. `status: pending-localization` this status tells that there are changes in the localization strings that need to be translated. When you make such changes, put this status badge without removing the other applicable ones and assign a person to do the translations. + +> Note: This status should be set only when the PR is approved. This will indicate that no further changes will be applied. +2. `status: localized` this status is for issues that were with a pending translation status and have already been localized. Place this status label once these translation changes have been included in the current pull request, or the changes are already pulled with a different pull request. + +> Note: Keep in mind that when you submit a change in the EN .md files, you don't need to make the same change in the JP/KR versions. This task will be handled by the Localization team. + + +## Fixing a bug + +1. Depending on where the bug/change/feature was found/is planned `the current version` or the `ongoing release version`, checkout a development branches from `vnext` or/and `master` branch. `vnext` is the version that is going to be used upon release (next version), and `master` is the branch with the current state (current version available on production). If the change/fix is applicable only to the ongoing release branch (`vnext`) there is no need to cherry-pick to `master` branch as the change/fix/feature will be pushed to `master` branch upon release. +2. Run lint +3. Pull request your changes and reference the issue. Use the enforced commit message format with applicable type, scope, etc. +4. Don't forget to make the necessary status updates, as described in the workflow section. + +> Note: Cherry-pick to `master` branch only changes with **high priority**. There is no need to cherry-pick into `master` every bug fix/change from `vnext`. A regular mass merge PRs are going to be made from `vnext` into `master`. + +**Example workflow for a bug with high priority** +The process will look like this: + +1. Checkout new branch from `vnext`. For code example purposes let's say the new branch is called `fixing-bug-5423-vnext`. +2. Commit your changes to your `fixing-bug-5423-vnext` branch. +3. Push and PR to the `vnext` branch. +4. Switch to the `master` branch. +5. Create a new branch from `master`. For code example purposes let's say the new branch is called `fixing-bug-5423-master`. +6. Cherry pick your commit from the `fixing-bug-5423-vnext` branch: `git cherry-pick fixing-bug-5423-master` +7. Push to your `fixing-bug-5423-master` branch and PR to the `master` branch. + +# Environment variables and template tokens + +MDX topics use curly-brace template tokens that are resolved per-platform at build time. The token values are defined in `docs/xplat/docConfig.json` under each platform key (`Angular`, `React`, `WebComponents`, `Blazor`). + +Common tokens used in MDX files: + +| Token | Example resolved value (Angular) | +|---|---| +| `{Platform}` | `Angular` | +| `{ProductName}` | `Ignite UI for Angular` | +| `{IgPrefix}` | `Igx` | +| `{PackageCore}` | `igniteui-angular-core` | +| `{PackageGrids}` | `igniteui-angular` | +| `{PackageCharts}` | `igniteui-angular-charts` | +| `{PackageGauges}` | `igniteui-angular-gauges` | +| `{PackageDockManager}` | `igniteui-dockmanager` | +| `{ComponentName}` | Replaced with the per-platform component name in shared templates | + +Use these tokens in MDX prose and code blocks so that a single source file produces correct output for all four platforms: + +```mdx +## {Platform} Grid Example + +Install the required packages: + +```cmd +npm install {PackageGrids} +npm install {PackageCore} +``` +``` + +To add or modify token values, edit `docs/xplat/docConfig.json`. + +# Sample / Code View Configuration + +To embed a live sample in an MDX topic, use the `` component from `igniteui-astro-components`. It renders an interactive iframe with optional StackBlitz/CodeSandbox launch buttons. + +Import it at the top of the MDX file alongside other imports: + +```mdx +import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; +``` + +Usage: + +```mdx + +``` + +| Attribute | Required | Notes | +|---|---|---| +| `src` | yes | Path to the sample relative to the platform samples base URL. | +| `height` | yes | Height of the sample iframe in pixels (numeric JSX expression, e.g. `{600}`). | +| `alt` | no | Accessible label for the iframe. Use `{Platform}` token so it resolves per-platform. | + +> Note: It is required to always set the `height` attribute so the sample area is properly sized. + +Example within a topic: + +```mdx +## {Platform} Grid Example + + +``` + +# PlatformBlock usage + +MDX topics in `docs/xplat/src/content/` are shared across all four platforms. Use `` to gate content that should only appear on specific platforms. + +Import at the top of the MDX file: + +```mdx +import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; +``` + +Syntax: + +```mdx + +```ts +// Angular-specific code +import { IgxGridModule } from 'igniteui-angular'; +``` + +``` + +Multiple platforms in one block: + +```mdx + +content visible on Angular and WebComponents only + +``` + +Valid platform names (exact casing): `Angular`, `React`, `WebComponents`, `Blazor`. + +> Note: Content that is identical across all platforms should be left unwrapped. Only platform-specific code snippets, notes, or prose must be wrapped. + +# ApiLink usage + +Use `` to link inline text and the API References section to platform-specific API documentation. A single `` tag resolves to the correct URL for each platform at build time. + +Import at the top of the MDX file: + +```mdx +import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +``` + +Basic syntax: + +```mdx + + + +``` + +Key attributes: + +| Attribute | Required | Notes | +|---|---|---| +| `pkg` | yes | Package key: `"grids"`, `"core"`, `"charts"`, `"gauges"`, `"excel"`, etc. | +| `type` | yes | Short type name **without** platform prefix — e.g. `"Grid"`, not `"IgrGrid"`. | +| `kind` | for non-classes | TypeDoc kind: omit for classes. Use `"enum"`, `"interface"`, or `"typeAlias"` otherwise. | +| `member` | no | Property or method name for anchor links. | +| `prefixed` | no | Default `true` (adds `Igr`/`Igx`/`Igc`/`Igb`). Set `{false}` for excel types and when `type` already contains `{ComponentName}`. | +| `exclude` | no | Comma-separated platforms to show as inline code instead of a link (e.g. `exclude="Blazor"`). Use when the type does not exist on those platforms. | +| `label` | no | Override the display text. | + +Also declare the types in the frontmatter so the auto-generated API reference grid works: + +```yaml +mentionedTypes: ["Grid", "Column"] +``` + +For a complete reference see [AI-AGENT-API-LINKS.md](../docs/xplat/AI-AGENT-API-LINKS.md). + +# Creating shared help topics + +The xplat documentation uses a single MDX source file shared across all four platforms (Angular, React, WebComponents, Blazor). Platform-specific content is gated with `` and platform-specific tokens (`{Platform}`, `{ComponentName}`, `{IgPrefix}`, etc.) are resolved at build time from `docConfig.json`. + +When creating a shared topic that covers multiple grid types (e.g. Grid, TreeGrid, HierarchicalGrid), use the `{ComponentName}` token in prose and code examples so the same file can be referenced from each grid's navigation entry with a different `{ComponentName}` value injected. Each generated output file gets its own resolved content without duplicating the MDX source. + +# Updating of Data Visualization related topics + +The cross-platform (xplat) documentation MDX source files live in this repository under `docs/xplat/src/content/`. Edit them directly here. The generated per-platform output is produced by the build scripts under `docs/xplat/scripts/`. + +If content originates from or must be synced with the upstream [`igniteui-xplat-docs`](https://github.com/IgniteUI/igniteui-xplat-docs) repository, use the merge scripts in `scripts/` (e.g. `merge-vnext-updates.mjs`, `migrate-vnext-new-files.mjs`) to pull in updates rather than editing generated files directly. + +# Adding of images in the topic + +Images in MDX topics use the Astro `` component for automatic optimization and lazy loading. Images must be placed in the `docs/xplat/public/images/` folder and imported at the top of the MDX file. + +Import pattern: + +```mdx +import { Image } from 'astro:assets'; +import myImage from '@xplat-images/general/my-image.png'; +``` + +Usage: + +```mdx +Description of the image +``` + +- Use the `@xplat-images` alias which resolves to `docs/xplat/public/images/`. +- Always provide a meaningful `alt` attribute. +- Use `{Platform}` in the `alt` text when the image is platform-generic (e.g. `alt="{Platform} Grid Overview"`). +- Responsive sizing and lazy loading are handled automatically by Astro — no extra classes or `data-srcset` attributes are needed. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/docs-issue.md b/.github/ISSUE_TEMPLATE/docs-issue.md new file mode 100644 index 0000000000..e0933c0924 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/docs-issue.md @@ -0,0 +1,52 @@ +--- +name: Documentation issue +about: Report incorrect, missing, or outdated documentation content +title: '' +labels: 'status: in-review' +assignees: '' +--- + +## Topic / URL + +Provide a link to the affected documentation page or the path to the MDX source file (e.g. `docs/xplat/src/content/en/components/grids/grid/overview.mdx`). + +--- + +## Platform(s) affected + +- [ ] Angular +- [ ] React +- [ ] WebComponents +- [ ] Blazor +- [ ] All platforms + +--- + +## Issue type + +- [ ] Incorrect or misleading content +- [ ] Missing content / feature not documented +- [ ] Outdated content (API change, version update) +- [ ] Broken link +- [ ] Broken or missing sample +- [ ] Code snippet error +- [ ] Typo / grammar +- [ ] Other + +--- + +## Description + + + +--- + +## Expected content + + + +--- + +## Additional context + + diff --git a/.github/ISSUE_TEMPLATE/docs-task.md b/.github/ISSUE_TEMPLATE/docs-task.md new file mode 100644 index 0000000000..37ae727b77 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/docs-task.md @@ -0,0 +1,49 @@ +--- +name: Documentation task / enhancement +about: Request new documentation, a topic update, or a content improvement +title: '' +labels: 'status: in-review' +assignees: '' +--- + +## Task type + +- [ ] New topic / component documentation +- [ ] Update existing topic (new release, API change, new feature) +- [ ] Add missing platform variant (Angular / React / WebComponents / Blazor) +- [ ] Improve existing content (clarity, examples, structure) +- [ ] Add or update code samples +- [ ] Other + +--- + +## Platform(s) + +- [ ] Angular +- [ ] React +- [ ] WebComponents +- [ ] Blazor +- [ ] All platforms + +--- + +## Description + + + +--- + +## Acceptance criteria + + + +--- + +## Related resources + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..2fd5a1bf3b --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,30 @@ +Closes # + +### Checklist: + + - [ ] check topic's TOC/menu and paragraph headings + - [ ] [Include TOC topic labels](https://github.com/IgniteUI/igniteui-docfx/blob/master/README.md#include-toc-topic-labels) in the topic content when it has a valuable update, is new, or is considered `preview` / `beta` + - [ ] link to other topics using `../relative/path.md` + - [ ] at the References section at the end of the topic add links to topics, samples, etc + - [ ] reference API documentation instead of adding a section with API + +
+ + - [ ] use valid component names - [Data] Grid, `IgxSelectComponent`, `` + - [ ] use spell checker tool (VS Code, Grammarly, Microsoft Editor) + - [ ] add inline `code blocks` for the names of classes / tags / properties + - [ ] add language descriptor for the ```code blocks``` + - [ ] check broken links (use browser add-on) + - [ ] check if sample is working and fully visible in the topic + - [ ] check if sample is working and fully visible in the StackBlitz + - [ ] check if code blocks match the code in StackBlitz demo + +
+ + - [ ] follow SEO guidelines to fill topic's metadata ([SEO guidelines](https://infragisticsinc297.sharepoint.com/:w:/g/Groups/marketing/EWz9InT4FDlErHCumxsKGY4Bd8H03yhRWxDFk47luRz-_Q?e=S5wWcx)) + +
+ + - [ ] do not resolve requested changes (leave that to the reviewer) + - [ ] add `pending-localization` label when the review of the PR is done + - [ ] add a member from the localization team to translate it diff --git a/.github/workflows/pr-stale.yml b/.github/workflows/pr-stale.yml new file mode 100644 index 0000000000..672e059b4c --- /dev/null +++ b/.github/workflows/pr-stale.yml @@ -0,0 +1,26 @@ +name: "Mark stale pull requests and issues" +on: + schedule: + # Run every day at midnight UTC + - cron: '0 0 * * *' + +jobs: + stale: + runs-on: ubuntu-latest + permissions: + issues: write + pull-requests: write + steps: + - uses: actions/stale@v9 # Use the actions/stale action + with: + remove-pr-stale-when-updated: true + days-before-stale: 30 + # days-before-pr-close: 7 + stale-issue-message: 'Auto-tagged as stale status because no activity in the last 30 days.' + stale-pr-message: 'Auto-tagged as stale status because no activity in the last 30 days.' + # It will be closed in 7 days if no further activity occurs. Thank you for your contributions. + # close-pr-message: 'This pull request has been closed due to inactivity.' + stale-pr-label: 'status: stale' + stale-issue-label: 'status: stale' + # exempt-pr-labels: 'keep-open, awaiting-upstream' # Labels to exempt from being marked stale + # https://github.com/actions/stale - arguments reference