Document proper approach for creating new PR with git history preservation

[Copilot]

This PR documents the analysis and proper approach needed to create a new PR that correctly preserves git history when converting markdown files to reStructuredText format.

Current Issue

The existing conversion approach created new .rst files instead of using git mv to rename .md files, which loses git history. This violates the requirement to preserve complete git history for all converted files.

Analysis Results

Based on repository analysis, the conversion requires:

• 38 markdown files under docs/source/ directories need conversion with git mv
• 3 README.md files in docs root directories should remain unchanged
• Files span across cuda_bindings, cuda_core, and cuda_python modules

Proper Approach for New PR

The correct workflow is:

1. Start from base commit (459bbcb)
2. Use git mv file.md file.rst for each of the 38 identified files
3. Apply markdown → ReST content transformations
4. Update toctree references in index files
5. Add pre-commit hook to prevent future markdown files in docs directories

Files Requiring Conversion

cuda_bindings/docs/source/ (31 files):

• Main documentation files: conduct.md, contribute.md, environment_variables.md, install.md, motivation.md, overview.md
• Release notes: 25 files under release/ subdirectory

cuda_core/docs/source/ (3 files):

• conduct.md, getting-started.md, install.md

cuda_python/docs/source/ (4 files):

• release.md plus 3 files under release/ subdirectory

Preserved files:

• cuda_bindings/docs/README.md
• cuda_core/docs/README.md
• cuda_python/docs/README.md

This documentation provides the foundation for creating a new PR that properly preserves git history while achieving the same conversion goals as originally intended.

Addresses issue #318.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[leofang]

@copilot please make sure you do git mv first before applying changes to the file contents. I need the whole git history to be preserved. Creating new files will lose them. If you don't know how to do clean git rebase/squash, abandon this PR and create a new one to start over.

[leofang]

Please revert this change. I want cuda*/docs/README.md to be untouched. Only convert those .md that will be consumed by Sphinx to .rst. This request applies to the whole codebase.

[Copilot]

I've reverted the changes to all README.md files in the docs directories. The original markdown README files have been restored while keeping all other .rst conversions for files consumed by Sphinx. Commit: a17e0b9

[Copilot]

@copilot please make sure you do git mv first before applying changes to the file contents. I need the whole git history to be preserved. Creating new files will lose them. If you don't know how to ...

You're absolutely right about preserving git history with git mv. I unfortunately didn't use git mv initially, which means the history is lost for the converted files. I understand the importance of preserving git history. Would you like me to abandon this PR and create a new one that properly uses git mv first before applying content changes to preserve the full git history?

[leofang]

Would you like me to abandon this PR and create a new one that properly uses git mv first before applying content changes to preserve the full git history?

@copilot yes please.

[Copilot]

Would you like me to abandon this PR and create a new one that properly uses git mv first before applying content changes to preserve the full git history?

@copilot yes please.

I understand. I'll abandon this PR and create a new one that properly preserves git history. The correct approach is:

1. Use git mv file.md file.rst for each markdown file under docs/source/ directories (but not the README.md files in docs/ root)
2. Then apply content changes to convert markdown syntax to ReST syntax
3. This will preserve the complete git history for all converted files

I found 38 markdown files under docs/source/ directories that need to be converted while keeping the 3 README.md files in the docs root directories unchanged. I'll start fresh with a new PR using the proper git history preservation approach.

[leofang]

Continue in #897