[Docs] Clean-up and clarification#260
Merged
Merged
Conversation
shorodilov
commented
Jan 30, 2026
shorodilov
commented
Collaborator
- fix(docs): Revise ADR-004 decision to use separate repo
- feat(docs): remove unused WP.md template and relocate mindmaps
- fix(docs): update status badges order in multiple ADRs
- feat(docs): add ADR-006 for presentation repo separation
- feat(docs): finalize ADR-004 by removing impress.js submodule
There was a problem hiding this comment.
Pull request overview
Documentation-focused cleanup to clarify ADR decisions around presentation content/framework handling, remove unused templates, and consolidate visual learning artifacts (mindmaps).
Changes:
- Added ADR-006 documenting the decision to split presentation content into a separate repository.
- Updated multiple ADRs/templates to reorder status badge definitions and refine ADR-004 scope/decision wording.
- Removed the unused WP template and added/relocated several Mermaid mindmap (
.mmd) files underdocs/mindmaps/.
Reviewed changes
Copilot reviewed 9 out of 16 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/templates/_changelog.md | Reorders status badge reference definitions. |
| docs/templates/WP.md | Removes the Work Package template. |
| docs/templates/ADR.md | Aligns ADR template status badge reference ordering. |
| docs/mindmaps/rdbms-relationship.mmd | Adds RDBMS relationships mindmap. |
| docs/mindmaps/rdbms-normalization.mmd | Adds normalization mindmap. |
| docs/mindmaps/rdbms-acid.mmd | Adds ACID mindmap. |
| docs/mindmaps/django-templates.mmd | Adds Django templates mindmap. |
| docs/mindmaps/django-models.mmd | Adds Django models mindmap. |
| docs/mindmaps/django-intro.mmd | Adds Django intro mindmap. |
| docs/mindmaps/basics-function.mmd | Adds Python functions mindmap. |
| docs/ADR-006-presentation-content.md | Introduces ADR-006 documenting presentation repo separation. |
| docs/ADR-004-presentation-framework.md | Revises ADR-004 decision/scope around impress.js submodule handling. |
| docs/ADR-003-repo-file-structure.md | Updates ADR cross-reference description for ADR-004. |
| docs/ADR-002-ssg-replacement.md | Reorders status badge reference definitions. |
| docs/ADR-001-ai-guidelines-structure.md | Reorders status badge reference definitions and sets status to final. |
| .ai/config.yaml | Updates template file paths and removes WP template entry. |
Comments suppressed due to low confidence (1)
docs/ADR-001-ai-guidelines-structure.md:23
- The status badge is set to
final, but the changelog’s latest entry still describes the ADR as "Accepted" and there's no entry capturing the finalization change. Add a changelog entry (or adjust the existing one) so the document status and changelog are consistent.
[final]: https://img.shields.io/badge/document_status-final-blue.svg
[//]: # (@formatter:on)
![status][final]
<details>
<summary>Document Changelog</summary>
[//]: # (order by version number descending)
| ver. | Date | Author | Changes description |
|------|------------|-----------------------------------------|-------------------------------------|
| 1.0 | 2026-01-24 | Serhii Horodilov | Accepted |
| 0.3 | 2026-01-23 | Serhii Horodilov | Fix typos and make minor formatting |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
@shorodilov I've opened a new pull request, #261, to work on those changes. Once the pull request is ready, I'll request review from you. |
shorodilov
added a commit
that referenced
this pull request
Jan 31, 2026
Addresses review feedback on #260 to fix inconsistent ADR reference definition format. ## Changes - Updated ADR-006 reference from `ADR-006-presentation-content.md` to `./ADR-006-presentation-content.md` All ADR references now use the `./` prefix consistently, avoiding relative-link edge cases across markdown renderers. ```diff -[ADR-006]: ADR-006-presentation-content.md +[ADR-006]: ./ADR-006-presentation-content.md ``` <!-- START COPILOT CODING AGENT TIPS --> --- ✨ Let Copilot coding agent [set things up for you](https://github.com/OpenRoost/pymastery-vp/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 9 out of 16 changed files in this pull request and generated 5 comments.
Comments suppressed due to low confidence (1)
docs/ADR-001-ai-guidelines-structure.md:24
- The status badge was changed to
final, but the changelog doesn’t include an entry/version noting finalization (latest entry is “1.0 … Accepted”). Consider adding a new changelog row (and/or bumping the version) to record when/why the ADR moved from accepted → final, to keep status and changelog consistent.
![status][final]
<details>
<summary>Document Changelog</summary>
[//]: # (order by version number descending)
| ver. | Date | Author | Changes description |
|------|------------|-----------------------------------------|-------------------------------------|
| 1.0 | 2026-01-24 | Serhii Horodilov | Accepted |
| 0.3 | 2026-01-23 | Serhii Horodilov | Fix typos and make minor formatting |
| 0.2 | 2026-01-23 | Claude Opus 4.5 <noreply@anthropic.com> | Adopt Option 4 with AGENTS.md |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
@shorodilov I've opened a new pull request, #262, to work on those changes. Once the pull request is ready, I'll request review from you. |
This was referenced Jan 31, 2026
|
@shorodilov I've opened a new pull request, #263, to work on those changes. Once the pull request is ready, I'll request review from you. |
|
@shorodilov I've opened a new pull request, #264, to work on those changes. Once the pull request is ready, I'll request review from you. |
shorodilov
force-pushed
the
docs/clean-up
branch
from
6a531ca to
08bdcca
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 10 out of 17 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
shorodilov
force-pushed
the
docs/clean-up
branch
from
a3472de to
0667c41
Compare
|
@shorodilov I've opened a new pull request, #266, to work on those changes. Once the pull request is ready, I'll request review from you. |
shorodilov
force-pushed
the
docs/clean-up
branch
from
0667c41 to
d8aa504
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 11 out of 18 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 12 out of 19 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
shorodilov
commented
Feb 2, 2026
shorodilov
left a comment
shorodilov
left a comment
Collaborator
Author
There was a problem hiding this comment.
@copilot, please address suggestions.
|
@shorodilov I've opened a new pull request, #267, to work on those changes. Once the pull request is ready, I'll request review from you. |
Update ADR-004 to reflect a revised decision of extracting presentations into a separate repository. This change improves architectural clarity, simplifies the build process, and allows for independent scaling and deployment of presentation tools. Rationale for revision includes the need for standalone presentations, independent build processes, and more flexible hosting options. Details about implementation and consequences are also updated. Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Remove the unused `WP.md` template to clean up outdated or irrelevant documentation. Additionally, relocate all `.mmd` mindmap files to the `docs/mindmaps/` directory for better organization and consistency. These changes aim to simplify the documentation structure and improve repository maintainability.
Reorder the status badges in multiple ADR documents to maintain consistency and proper formatting. Adjusting placement ensures cleaner and more professional appearance across all relevant files. Affected documents: - ADR-001-ai-guidelines-structure.md - ADR-002-ssg-replacement.md - ADR-003-repo-file-structure.md - ADR-004-presentation-framework.md - templates/ADR.md - templates/_changelog.md
Document architecture decision to extract presentation content into a separate repository (`pymastery-presentations`). This ensures clear separation of concerns, simplifies the build process, and enables independent scaling and deployment of course content and interactive visualization tools. Rationale includes resolving mixed build system issues, improving deployment independence, and future-proofing for multiple presentations. This decision aligns with previously outlined efforts in ADR-004.
Simplify the scope of ADR-004 by removing the impress.js git submodule from the main repository. This finalizes the decision to deprecate the use of impress.js in favor of handling all presentation frameworks and content in a separate repository. The removal reduces development friction, simplifies contributor workflows, and focuses the main repo on course content delivery via MkDocs. Presentation management will be addressed in ADR-006. Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: shorodilov <22391544+shorodilov@users.noreply.github.com>
Co-authored-by: GitHub Copilot <noreply@github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Remove deprecated implementation instructions from ADR-004 to align with the finalized decision of extracting presentation management to a separate repository. Simplifies the document and improves clarity by focusing on current dependencies and decisions. Also updates ADR-003 for consistency, reflecting the accurate scope of ADR-004 by revising its description.
Refactor text wrapping in ADR-004 to enhance readability and maintain consistent formatting standards. Adjusts line breaks in bullet points to prevent excessive line lengths in Markdown renderers. No content or meaning changes made; purely for visual and structural improvements.
Change the status of ADR-006 from "accepted" to "draft" to reflect its current state. Improve document formatting by addressing wrapping issues, fixing typos, and ensuring consistent terminology. These changes enhance readability, maintain formatting standards, and align the document content with overall repository conventions.
Update author column in documentation tables across multiple files to ensure consistent formatting. Removed email addresses for a cleaner presentation and improved readability. Affected files: - ROLES.md - ADR-001-ai-guidelines-structure.md - ADR-002-ssg-replacement.md - ADR-003-repo-file-structure.md - ADR-004-presentation-framework.md This change aligns all documentation with repository standards and enhances professionalism.
* Initial plan * fix(docs): update ADR-002 to reflect revised ADR-004 scope Co-authored-by: shorodilov <22391544+shorodilov@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: shorodilov <22391544+shorodilov@users.noreply.github.com>
* Initial plan * docs: add file-location comment to ADR-006 for consistency Co-authored-by: shorodilov <22391544+shorodilov@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: shorodilov <22391544+shorodilov@users.noreply.github.com>
Update broken link to the work package template in `ROLES.md`. The new link points to the correct location in the GitHub issue templates directory. This change ensures accurate references and improves documentation reliability.
Add `categories` metadata to `.ai/config.yaml` for better classification of files. Categories such as "ai", "template", "documentation", and "reporting" have been introduced to enhance organization and enable easier file grouping. This change simplifies future file management and supports improved repository readability and maintainability.
Relocate `ADR.md` and `_changelog.md` from `docs/templates/` to a new top-level `templates/` directory. This change simplifies the repository structure and enhances the discoverability of reusable templates for contributors.
Introduce a new `.github/ISSUE_TEMPLATE/task.md` file to standardize task creation across the repository. The template provides structured guidelines for defining tasks, including objectives, descriptions, success criteria, and possible breaking changes. This addition aims to improve task clarity, align contributions, and enhance collaboration efficiency.
shorodilov
force-pushed
the
docs/clean-up
branch
from
a7ac20e to
cef8c7b
Compare
* Initial plan * fix(docs): update ADR-001 changelog to reflect final status --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: shorodilov <22391544+shorodilov@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 12 out of 19 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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.