My workflow for contributing to documentation, to avoid issues!

[ylevental]

I'm working on a Codecademy Docs contribution. Follow this exact workflow:

ISSUE DETAILS:

• Issue #: [FILL: e.g., 7815]
• Library/Concept: [FILL: e.g., matplotlib, PyTorch, NumPy]
• Method/Function: [FILL: e.g., .axis(), .igamma()]
• Issue URL: [OPTIONAL: paste GitHub issue URL]

MY SETUP:

• System: Fedora 42
• Docs repo location: ~/Documents/docs
• GitHub username: ylevental
• My fork: https://github.com/ylevental/docs

WORKFLOW YOU MUST FOLLOW:

PHASE 1 - Clean Start (I'll run these, after you edit last line and re-print the entire block):

rm -rf ~/Documents/docs
cd ~/Documents
git clone https://github.com/ylevental/docs.git
cd docs
git remote add upstream https://github.com/Codecademy/docs.git
git fetch upstream
git merge upstream/main
git push origin main
git checkout -b add-[feature-name]

PHASE 2 - YOU INVESTIGATE FIRST:
Before creating ANY files:

1. Use Filesystem:search_files to locate the concept directory
2. Use Filesystem:directory_tree to examine structure
3. Check 2-3 existing term files to understand the pattern
4. VERIFY the concept file already exists (e.g., matplotlib.md, pytorch.md)
5. Tell me the EXACT path where the new term file should go
6. Show me the directory structure you found

PHASE 3 - YOU CREATE FILE:

1. Create the complete .md file with:
   • YAML front matter
   • Description
   • Syntax section
   • Example section
   • Codebyte example
2. Create it in the CORRECT location you verified in Phase 2
3. Give me the exact commands to format and push

PHASE 4 - I FORMAT & PUSH:
I'll run the commands you give me.

PHASE 5 - PR TEMPLATE:
Give me the complete PR title and description with the CORRECT file path.

CRITICAL RULES:

• ALWAYS check existing structure BEFORE creating files
• NEVER assume file locations
• ALWAYS use Filesystem tools to verify paths
• The concept file (e.g., matplotlib.md) must already exist
• Format with: yarn prettier --write [file-path]

[ylevental]

And now for editing:

I'm working on revising a Codecademy Docs PR based on reviewer feedback. Follow this exact workflow:

PR DETAILS:

• PR #: [FILL: e.g., 7815]
• Branch name: [FILL: e.g., add-matplotlib-axis]
• PR URL: [FILL: paste GitHub PR URL]

REVIEWER REQUEST:
[FILL: Paste the exact reviewer comment, e.g., "Please add output images and link them in the markdown file"]

MY SETUP:

• System: Fedora 42
• Docs repo location: ~/Documents/docs
• GitHub username: ylevental
• My fork: https://github.com/ylevental/docs

WORKFLOW YOU MUST FOLLOW:

PHASE 1 - UNDERSTAND THE REQUEST:

1. Read the reviewer's comment carefully
2. Identify what needs to be changed/added
3. Ask me clarifying questions if the request is unclear
4. Summarize what you understand needs to be done

PHASE 2 - INVESTIGATE EXISTING STRUCTURE:

FIRST: Check if repo exists on hard drive

• Use Filesystem:list_directory on ~/Documents/docs
• If it EXISTS: Use Filesystem tools to read files
• If it DOESN'T EXIST: Use web_fetch to read files from GitHub

If using web_fetch:

1. Fetch the current PR file from: https://raw.githubusercontent.com/ylevental/docs/[branch-name]/[file-path]
2. Fetch 2-3 similar files from the main repo to understand the pattern
3. Tell me EXACTLY what you found and what needs to change

If using Filesystem:

1. Use Filesystem:search_files to locate the existing PR files
2. Use Filesystem:read_file to read the current file(s)
3. Check 2-3 similar EXISTING files to understand the correct format
4. Tell me EXACTLY what you found and what needs to change
5. Show me examples from similar files that demonstrate the correct pattern

PHASE 3 - FRESH START SETUP:
Give me this exact command block (edit the branch name):

rm -rf ~/Documents/docs
cd ~/Documents
git clone https://github.com/ylevental/docs.git
cd docs
git remote add upstream https://github.com/Codecademy/docs.git
git fetch upstream
git merge upstream/main
git push origin main
git checkout [branch-name]

PHASE 4 - YOU CREATE REQUIRED FILES:
Based on what you found in Phase 2:

1. If creating NEW files (e.g., images):
   • Generate them using appropriate tools
   • Save to /mnt/user-data/outputs/ with proper names
   • Provide download links
2. If UPDATING existing files:
   • Create the corrected version
   • Save to /mnt/user-data/outputs/ as [filename]-updated.md or similar
   • Provide download link
   • Highlight what changed

PHASE 5 - YOU CREATE UPDATE SCRIPT:
Create a bash script that:

1. Waits for me to download any files you created (images, updated markdown)
2. Copies/updates all necessary files to correct locations
3. Stages the changes with git add
4. Either amends the last commit OR creates a new commit
5. Handles the push (force or regular)

Save script to /mnt/user-data/outputs/ and provide download link.

PHASE 6 - I DOWNLOAD & RUN:
I'll download any files you created, then execute your script and paste the output.

PHASE 7 - VERIFY LINKS:
CRITICAL: If adding images or external files:

• Links MUST point to: https://raw.githubusercontent.com/ylevental/docs/[branch-name]/media/[filename]
• NOT to the main Codecademy repo (those files don't exist yet!)
• Verify links will work for the reviewer

PHASE 8 - RESPONSE TO REVIEWER:
Give me a suggested comment to post on the PR, such as:
"@Reviewer - I've added the output images and linked them in the markdown file. The images are now visible in the PR. Please let me know if any other changes are needed!"

CRITICAL RULES:

• ALWAYS check if repo exists BEFORE trying to read files
• Use web_fetch if repo doesn't exist locally
• ALWAYS check existing similar files for the correct format
• NEVER assume - verify everything first
• Image/media links must point to YOUR fork and YOUR branch during PR review
• Be explicit about whether to use --force push or regular push
• Check if merge conflicts need handling
• Provide the COMPLETE updated file, not just snippets
• Save ALL generated files to /mnt/user-data/outputs/ so I can download them

COMMON REVISION TYPES:

1. Add output images: Generate images, add to media/, update markdown with links
2. Fix formatting: Check similar files, match their exact style
3. Add missing sections: Look at 3+ examples, follow the pattern
4. Fix syntax errors: Read the file, locate issues, provide corrected version
5. Update descriptions: Ensure consistency with similar entries

CONFLICT HANDLING:
If git merge conflicts occur:

• Tell me to use git merge --abort
• Then use git push origin [branch] --force instead
• Explain why this is safe (we're replacing our own branch)

FILE DOWNLOAD LOCATIONS:
When you create files, I'll download them to:

• Updated markdown files → ~/Downloads/
• Images → ~/Downloads/
• Bash scripts → ~/Downloads/ (or just ~/ for quick access)