Conversation
blindzero
added this to the
v1.0.0 - Stable Contracts & Finishing for the release milestone
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR performs a comprehensive rewrite of the "About" and "Use" sections of the IdLE documentation, consolidating content, adding new workflow template examples, and updating navigation structure.
Changes:
- Consolidated documentation by removing
docs/use/steps.md,docs/use/configuration.md, anddocs/about/architecture.md, merging their content into other files - Added 7 new workflow template examples demonstrating AD, EntraID, and Exchange Online scenarios
- Significantly expanded
docs/about/concepts.mdto include architectural concepts and workflow/step documentation - Restructured
docs/use/workflows.mdto combine workflow and step documentation - Updated cross-references and links throughout documentation files
Reviewed changes
Copilot reviewed 27 out of 36 changed files in this pull request and generated 17 comments.
Show a summary per file
| File | Description |
|---|---|
| website/sidebars.js | Removed navigation entries for deleted docs (architecture, configuration, steps) |
| examples/workflows/templates/*.psd1 | Added 7 new workflow template examples for AD, EntraID, and Exchange Online scenarios |
| docs/use/workflows.md | Merged steps documentation, expanded with step types, conditional steps, and template substitution details |
| docs/use/steps.md | Removed - content merged into workflows.md |
| docs/use/configuration.md | Removed - content consolidated into concepts.md |
| docs/use/quickstart.md | Rewritten to focus on repository demo and first workflow execution |
| docs/use/providers.md | Expanded with provider aliases, authentication, and usage examples |
| docs/use/installation.md | Simplified and reorganized installation instructions |
| docs/about/concepts.md | Significantly expanded with responsibilities, planning, execution, and component details |
| docs/about/architecture.md | Removed - content moved to concepts.md and extensibility.md |
| docs/about/intro.md | Added context about JML processes and IdMS systems |
| docs/about/security.md | Minor content reorganization |
| docs/extend/*.md | Content reorganization and reference updates |
| docs/reference/*.md | Updated cross-references |
| Root documentation files | Updated references to removed architecture.md |
Contributor
|
@blindzero I've opened a new pull request, #129, to work on those changes. Once the pull request is ready, I'll request review from you. |
13 tasks
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 31 out of 40 changed files in this pull request and generated 3 comments.
Comments suppressed due to low confidence (1)
AGENTS.md:31
- These file paths reference
docs/advanced/security.mdanddocs/advanced/provider-capabilities.md, but these files don't exist in the repository. Based on the PR changes,security.mdhas been moved todocs/about/security.md. These references should be updated to point to the correct locations.
- `docs/advanced/security.md` (trust boundaries)
- `docs/advanced/provider-capabilities.md` (Capability rules)
- `docs/reference/providers-and-contracts.md` (Provider contracts)
- `docs/reference/steps-and-metadata.md` (Step metadata/capabilities usage)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 31 out of 40 changed files in this pull request and generated 4 comments.
Comments suppressed due to low confidence (1)
AGENTS.md:31
- Reference path is outdated. The file
docs/advanced/security.mdhas been moved todocs/about/security.mdas part of the documentation restructure, but this reference was not updated. The same issue exists on lines 29-30 which reference files indocs/advanced/anddocs/reference/that may not exist or have been moved.
- `docs/advanced/security.md` (trust boundaries)
- `docs/advanced/provider-capabilities.md` (Capability rules)
- `docs/reference/providers-and-contracts.md` (Provider contracts)
- `docs/reference/steps-and-metadata.md` (Step metadata/capabilities usage)
| Each step type's implementation is made available via a step registry. | ||
| Additionally, each step type's implementation defines required capabilities for this step. | ||
| Later, provider implementations are providing these capabilities for the steps. | ||
| If a provider selected for a step does not have the capabilities required by the step type, the workflow plan with fail. |
There was a problem hiding this comment.
Typo: "plan with fail" should be "plan will fail".
Suggested change
| If a provider selected for a step does not have the capabilities required by the step type, the workflow plan with fail. | |
| If a provider selected for a step does not have the capabilities required by the step type, the workflow plan will fail. |
|
|
||
| - **What** should happen is defined in a **workflow** (data-only configuration). | ||
| - **How** it happens is implemented by **steps** and **providers** (pluggable modules). | ||
| - **steps** define, via StepTypes, which provider-agnostic **capabilities** are required to perform a workflow step |
There was a problem hiding this comment.
Grammar issue: "While steps define by StepTypes" should be "While steps are defined by StepTypes" or "While steps define, via StepTypes,".
| Step types are treated as **contracts**. Prefer fully-qualified ids (module + step name), for example: `IdLE.Step.EmitEvent`. | ||
| Each step type's implementation is made available via a step registry. | ||
| Additionally, each step type's implementation defines required capabilities for this step. | ||
| Later, provider implementations are providing these capabilities for the steps. |
There was a problem hiding this comment.
Grammar issue: "provider implementations are providing" is awkward. Should be "provider implementations provide" or "providers provide".
Suggested change
| Later, provider implementations are providing these capabilities for the steps. | |
| Later, provider implementations provide these capabilities for the steps. |
| ### 1. Show Demo Workflows | ||
|
|
||
| The repository contains a demo runner that showcases the full **Plan → Execute** flow using predefined example workflows. | ||
| By default the **IdLE Demo** script uses only examples workflow definition from the `examples/workflows/mock` folder category to avoid dependency to real-life systems. |
There was a problem hiding this comment.
Grammar issue: "uses only examples workflow definition" should be "uses only example workflow definitions" (plural) or "uses only the example workflow definition".
Suggested change
| By default the **IdLE Demo** script uses only examples workflow definition from the `examples/workflows/mock` folder category to avoid dependency to real-life systems. | |
| By default the **IdLE Demo** script uses only example workflow definitions from the `examples/workflows/mock` folder category to avoid dependency to real-life systems. |
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Full revisit of
AboutandUsesection ofdocsand website.Motivation
Improving documentation.
Type of Change
Please select the relevant option:
Testing