diff --git a/.cursor/README.md b/.cursor/README.md new file mode 100644 index 0000000000..c0ea72c8f2 --- /dev/null +++ b/.cursor/README.md @@ -0,0 +1,123 @@ +# Cursor configuration for W&B documentation + +This directory contains Cursor-specific prompts and configurations for AI agents working with the W&B documentation repository. These prompts are optimized for use with Cursor while maintaining human readability. + +> **Note**: The format used here (Markdown with XML-like tags) is based on community best practices. Cursor has not published an official specification for `.cursor/` directory contents at the time of writing. + +## Directory structure + +### Core configuration files + +#### `rules.md` +Core project rules and conventions that apply to all work in this repository. Includes: +- Mandatory rules (what to always/never do) +- Repository structure overview +- Security and collaboration guidelines +- General project context + +#### `style.md` +Comprehensive style guide for W&B documentation covering: +- Detailed writing style rules +- Product naming conventions +- Accessibility guidelines +- Code example patterns +- Punctuation and formatting standards + +#### `docs.md` +Documentation-specific guidelines including: +- Role definition for documentation contributors +- Documentation philosophy and values +- Content organization patterns +- Writing patterns and templates +- Quality checklists + +### `runbooks/` +Task-specific prompts for complex operations: +- Step-by-step instructions for recurring tasks +- Formatted for optimal AI agent consumption +- Includes context, prerequisites, and troubleshooting + +## How to use these prompts + +### For Cursor users +1. Cursor detects that `.cursor/` files exist but does NOT automatically load their contents. +2. You still need to prompt the agent to read these files. +3. Use the example prompts below to direct your agent to these guidelines. + +### For other AI tools +1. Provide relevant files as context when starting a session. +2. Reference specific sections when needed. +3. The structured format with XML-like tags aids parsing. + +### Example prompts to direct your agent + +Since agents don't automatically load file contents (even in Cursor), use these prompts to ensure they follow the guidelines: + +**Before starting work:** +``` +Please read .cursor/rules.md and .cursor/style.md to understand the project conventions, then help me with my task. +``` + +**When reviewing changes:** +``` +Review your proposed changes against .cursor/style.md and make any necessary adjustments to match the style guidelines. +``` + +**For specific tasks:** +``` +Check .cursor/runbooks/ for any relevant runbooks before proceeding with [task description]. +``` + +**To ensure consistency:** +``` +Before editing [filename], use grep to check how similar concepts are documented in this directory, then match that style. +``` + +## Key differences from `.ai/` directory + +| Aspect | `.ai/` Directory | `.cursor/` Directory | +|--------|-----------------|-------------------| +| Format | Natural language prose | Structured with XML-like tags | +| Target | Human-readable first | AI-optimized, human-readable | +| Organization | Topic-based files | Role-based separation | +| Usage | Manual context provision | Automatic loading in Cursor | + +## Maintenance guidelines + +### When to update these files +- When documentation standards change +- When new patterns emerge +- When common issues need addressing +- When new runbooks are needed + +### How to update +1. Maintain the structured format with clear sections. +2. Keep XML-like tags for major sections. +3. Ensure human readability alongside AI optimization. +4. Test changes with actual documentation tasks. + +### Creating new runbooks +1. Copy the template from `runbooks/TEMPLATE.md` +2. Fill in all sections with specific details. +3. Include all gotchas and edge cases discovered. +4. Test with an AI agent before finalizing. + +## Security notes + +- Some runbooks require W&B employee access (clearly marked) +- Never include sensitive information (API keys, passwords, internal URLs) +- These files are in a public repository + +## Related resources + +- `.ai/` directory - Natural language versions of these prompts +- Main repository README - Overall repository documentation +- [W&B Documentation Site](https://docs.wandb.ai) - The live documentation + +## Contributing + +When updating these configurations: +1. Ensure consistency with existing patterns. +2. Test changes with real documentation tasks. +3. Keep both human and AI usability in mind. +4. Update both `.cursor/` and `.ai/` directories if applicable. diff --git a/.cursor/docs.md b/.cursor/docs.md new file mode 100644 index 0000000000..5fc468dcf7 --- /dev/null +++ b/.cursor/docs.md @@ -0,0 +1,363 @@ +# W&B documentation guidelines + +This file contains specific guidelines for working with the W&B documentation repository. + +> **Tip**: To help save context tokens, agents do not automatically load prompts like these documentation guidelines. To ask your agent to load and use these guidelines, prompt it with: "Read .cursor/docs.md for documentation-specific patterns and guidelines." + +## Your role as a documentation contributor + + +You are a member of the W&B (Weights & Biases) documentation team, helping to create and maintain clear, accurate, and accessible documentation for W&B users across all experience levels—from ML beginners to advanced practitioners. + +As a W&B docs team member, you: +- Write and edit documentation that helps users successfully use W&B products. +- Ensure technical accuracy while maintaining clarity and accessibility. +- Follow established patterns and conventions to maintain consistency. +- Help both human users and AI agents understand W&B's capabilities. + + + +## Documentation philosophy + + +### Core values +1. **User Success**: Every piece of documentation should help users accomplish their goals +2. **Progressive Disclosure**: Start simple, add complexity as needed +3. **Self-Contained Pages**: Users should find what they need without excessive navigation +4. **Practical Examples**: Show real-world usage, not just API signatures +5. **Global Audience**: Write for users with varying English proficiency and cultural backgrounds + +### What makes good documentation +- **Clear Purpose**: Each page has one primary goal +- **Scannable Structure**: Users can quickly find what they need +- **Complete Examples**: Code that users can copy and run +- **Troubleshooting Help**: Common issues and their solutions +- **Next Steps**: Guide users to related topics. + + + +## Content organization + + +### Page types + +#### Quickstart guides +- Goal: Get users running in under 5 minutes. +- Structure: Prerequisites → Installation → First Success → Next Steps. +- Keep it minimal - link to detailed guides for more. + +#### How-to guides +- Goal: Help users complete specific tasks. +- Structure: Prerequisites → Steps → Verification → Troubleshooting. +- Focus on one task per guide. + +#### Conceptual docs +- Goal: Explain how W&B works and why. +- Structure: Overview → Key Concepts → Architecture → Examples. +- Use diagrams when helpful. + +#### Reference docs +- Goal: Provide complete API/configuration details. +- Structure: Summary → Parameters → Returns → Examples → Related. +- Be exhaustive but organized. + +#### Tutorials +- Goal: Teach through building something real. +- Structure: What to Build → Prerequisites → Steps → Final Code → Extensions. +- Make it engaging and practical. + + + +## Writing patterns + + +### Opening sections + +Start pages with context: +```markdown +# [Page Title] + +[One-sentence description of what this page covers] + +This guide shows you how to [specific task]. In this guide, you: +- [Outcome 1] +- [Outcome 2] +- [Outcome 3] +``` + +### Prerequisites pattern + +Be specific about requirements: +```markdown +## Prerequisites + +Before you begin, ensure you have: +- **W&B account**: [Sign up free](https://wandb.ai/signup) if you don't have one. +- **Python 3.8+**: With pip installed for package management. +- **Basic Python knowledge**: Familiarity with functions and imports. +- **GPU access** (optional): For faster training in examples. +``` + +### Step-by-step instructions + +Number steps and use clear imperatives: +```markdown +## Set up your environment + +1. **Install W&B**: + ```bash + pip install wandb + ``` + +2. **Authenticate your account**: + ```bash + wandb login + ``` + + When prompted, paste your API key from [wandb.ai/authorize](https://wandb.ai/authorize). + +3. **Verify installation**: + ```python + import wandb + print(wandb.__version__) + ``` +``` + +### Code examples pattern + +Make examples complete and runnable: +```markdown +## Complete example + +Here's a minimal example that logs metrics to W&B: + +```python +import wandb +import random + +# Initialize a new run +with wandb.init(project="my-first-project") as run: + # Simulate training loop + for epoch in range(10): + # Log metrics + run.log({ + "epoch": epoch, + "loss": random.random(), + "accuracy": random.random() + }) + + # Save a summary metric + run.summary["best_accuracy"] = 0.95 + +print("✅ Metrics logged to W&B!") +``` + +View your results at: [wandb.ai](https://wandb.ai) +``` + + + +## Technical accuracy + + +### Verification requirements + +1. **API Accuracy**: Cross-check all code against the [official API docs](https://docs.wandb.ai/ref/python/) +2. **Version Compatibility**: Note version requirements when APIs change +3. **Platform Differences**: Mention platform-specific considerations (Windows, Mac, Linux) +4. **Performance Impact**: Note if operations are expensive or slow +5. **Deprecation Warnings**: Clearly mark deprecated features + +### Testing code examples + +Before including code: +1. Run it in a clean environment. +2. Verify it produces expected output. +3. Check for common error cases. +4. Ensure imports are complete. +5. Test with current W&B version. + +### Common technical patterns + +#### Context managers (preferred) +```python +with wandb.init(project="my-project") as run: + run.log({"metric": value}) +``` + +#### Explicit cleanup (when needed) +```python +run = wandb.init(project="my-project") +try: + run.log({"metric": value}) +finally: + run.finish() +``` + +#### Error handling +```python +try: + with wandb.init(project="my-project") as run: + run.log({"metric": value}) +except wandb.Error as e: + print(f"W&B error: {e}") +``` + + + +## Common documentation tasks + + +### Critical: Working with existing content + +**The challenge**: Agents don't automatically scan surrounding content, but consistency is paramount. + +#### Quick context check (minimum for small edits) +For minor updates, at minimum: +1. Read the section you're editing (use `read_file` with offset/limit if file is large). +2. Scan for obvious patterns in that section. +3. Match the immediate surrounding style. + +#### Thorough context check (for significant edits) +For new sections or major updates: +1. Read the entire file you're editing. +2. Check 1-2 similar files in the same directory. +3. Use `grep` to find how key terms are used elsewhere. +4. Note patterns for: capitalization, punctuation, code structure, terminology. + +#### Efficient pattern detection +Instead of reading everything, use targeted searches: +```bash +# Quick checks for common patterns: +grep -n "## " file.md # How are headings formatted? +grep "wandb.init" file.md # What code patterns are used? +grep -E "- .{20,}$" file.md # Do list items have periods? +grep "W&B [A-Z]" file.md # How are product names capitalized? +``` + +**Remember**: Even a 30-second context check prevents inconsistencies that take much longer to fix in review. + +### Adding a new feature + +1. Propose whether it fits in existing docs or needs new page (humans should validate this architectural decision with full context before creating a draft PR). +2. Follow the quickstart → how-to → reference progression. +3. Include practical example using the feature. +4. Add to relevant index/navigation pages. +5. Cross-link from related pages. + +### Updating existing docs + +1. Read the entire page first. +2. Match existing style and structure. +3. Update all examples if API changed. +4. Check if other pages need updates too. +5. Preserve helpful existing content. + +### Documenting integrations + +1. Start with why someone would use this integration. +2. Show the simplest working example. +3. Cover common configuration options. +4. Include troubleshooting section. +5. Link to integration's own docs. + +### Writing troubleshooting sections + +Structure problems consistently: +```markdown +### [Problem]: [Brief description] + +**Symptoms**: What users see when this happens + +**Common causes**: +- Cause 1 +- Cause 2 + +**Solutions**: +1. Try this first (easiest). +2. If that doesn't work, try this. +3. Last resort option. + +**Prevention**: How to avoid this issue +``` + + + +## Quality checklist + + +Before submitting documentation: + +### Content quality +- [ ] Page has clear, single purpose +- [ ] All code examples are tested and working +- [ ] Technical details are accurate +- [ ] Troubleshooting covers common issues +- [ ] Links are valid and helpful + +### Writing quality +- [ ] Follows W&B style guide +- [ ] Clear, concise sentences +- [ ] Proper heading hierarchy +- [ ] Good use of formatting +- [ ] No typos or grammar errors + +### User experience +- [ ] Easy to scan and navigate +- [ ] Progressive complexity +- [ ] Self-contained (minimal required jumping) +- [ ] Clear next steps +- [ ] Accessible to global audience + +### Technical standards +- [ ] Code follows repository patterns +- [ ] Uses only public APIs +- [ ] Includes error handling where appropriate +- [ ] Performance implications noted +- [ ] Platform differences mentioned + + + +## Special considerations + + +### Multi-language support + +- Repository supports English (en), Japanese (ja), and Korean (ko). +- Focus on English docs first. +- Keep sentences simple for easier translation. +- Avoid idioms and cultural references. +- Use consistent terminology. + +### SEO and discoverability + +- Use descriptive page titles. +- Include relevant keywords naturally. +- Write clear meta descriptions. +- Use semantic HTML structure. +- Create descriptive headings. + +### Maintenance + +- Date-stamp time-sensitive content. +- Note version requirements. +- Plan for API deprecations. +- Keep examples current. +- Monitor user feedback. + + + +## Getting help + + +When working on documentation: + +1. **Check existing patterns** in similar docs +2. **Refer to style guide** for formatting questions +3. **Test all code examples** before submitting +4. **Ask for clarification** when requirements are unclear +5. **Get review** from team members for major changes + +Remember: Documentation is a team effort. When in doubt, ask for guidance rather than guessing. + + diff --git a/.cursor/rules.md b/.cursor/rules.md new file mode 100644 index 0000000000..cf1f62e99c --- /dev/null +++ b/.cursor/rules.md @@ -0,0 +1,176 @@ +# W&B documentation project rules + +This file defines the core rules and conventions for the W&B documentation repository. + +> **Tip**: To help save context tokens, agents do not automatically load prompts like these project rules. To ask your agent to load and use these rules, prompt it with: "Read `.cursor/rules.md` to understand the mandatory rules for this project." + +## Project overview + +This is the official repository repository for W&B (Weights & Biases) documentation, including: +- **[W&B Models](https://docs.wandb.ai/guides/models/)** (MLOps): Experiment tracking, sweeps, artifacts, and more. +- **[W&B Weave](https://weave-docs.wandb.ai/)** (LLMOps): Tracing, evaluations, and monitoring for LLM applications. +- **[W&B Inference](https://docs.wandb.ai/guides/inference/)** (Foundation Model APIs): Access to open-source foundation models through an OpenAI-compatible API. +- **Core features** of W&B: Registry, reports, automations. +- **Integrations**: Support for major ML frameworks and cloud platforms. + +## Repository structure + +- `/content/`: Main documentation content organized by language (`en`, `ja`, `ko`). In general, only English content. Separate processes exist for updating translations. +- `/assets/`: Images and other static resources. +- `/.ai/`: Natural language resources for AI agents (human-readable format). +- `/.cursor/`: Prompts and configurations in Cursor format (this directory). + +## Core documentation principles + + + +1. **Clarity over cleverness**: Write simple, direct sentences that convey information efficiently. +2. **User-focused**: Always consider what the reader needs to accomplish their task. +3. **Accuracy**: Verify technical details against the public API documentation and actual product behavior. +4. **Consistency**: Follow existing patterns in the documentation before creating new ones. +5. **Accessibility**: Write for a global audience with varying levels of English proficiency and technical expertise. + + + +## Mandatory rules + + + +1. **Always check existing content style BEFORE editing** - Read the file and nearby files first +2. **Never use emojis in documentation content** - They cause accessibility and translation issues +3. **Never include Latin abbreviations** (e.g., i.e., etc., vs., via) - Use plain English equivalents +4. **Never create new documentation files unless explicitly requested** +5. **Never mix style changes with content changes in the same PR** +6. **Never use private or undocumented APIs in examples** +7. **Always use context managers for `wandb.init()` in code examples** +8. **Always reference only public APIs documented in the API reference** +9. **Always match existing content style when editing near existing content** + +### The prime directive: Match existing style + +When editing documentation, your first priority is consistency with the existing corpus. Before making any changes: +1. **Read the entire file** you're editing. +2. **Check nearby files** in the same directory. +3. **Identify established patterns** for formatting, terminology, and structure. +4. **Match those patterns** even if they differ from this style guide. + +This approach ensures: +- Reviewers see consistent changes. +- The documentation maintains a unified voice. +- Style evolution happens deliberately, not accidentally. + + + +## Style guidelines + + + + +### Headings +- Use sentence case for all headings (capitalize only the first word and proper nouns). +- Examples: + - ✓ "Get started with W&B" + - ✗ "Getting Started with W&B" + +### Product names +- **Company name**: W&B (not Weights & Biases) in running text. +- **First mention pattern**: Use "W&B [Product]" on first mention, then drop "W&B" for subsequent mentions. +- **Capitalization patterns**: + - Products remain capitalized: W&B Weave → Weave, W&B Models → Models + - Some features become lowercase: W&B Run → run, W&B Sweep → sweep + - Special case: W&B artifact (lowercase even on first mention) + +### Voice and tone +- Direct and concise. +- Second person ("you") for instructions. +- Active voice preferred. +- Present tense for descriptions. +- Simple verbs over gerunds. + +### Punctuation +- Use straight quotes and apostrophes (not curly/smart quotes). +- Avoid exclamation points, ellipses, semicolons, em/en dashes. +- Include periods for complete sentences and long phrases in lists. + + + +## Code examples + + + +1. **Follow public API documentation patterns** - Check https://docs.wandb.ai/ref/python/ for recommended usage +2. **Always use context managers** for `wandb.init()`: + ```python + with wandb.init(project="my-project") as run: + run.log({"metric": value}) + ``` +3. **Specify language identifiers** in code blocks (python, bash, yaml, json) +4. **Include necessary imports and setup** - Examples should be self-contained and runnable +5. **Test code examples when possible** to ensure they work + + + +## Formatting standards + + + +- **Use spaces, not tabs**: 2 spaces per indentation level. +- **Trim trailing whitespace**: Remove trailing spaces on all lines. +- **EditorConfig**: The repository includes an `.editorconfig` file that enforces these settings. +- **Markdown details**: See [`style.md` Format specification](style.md#format-specification) for complete formatting conventions including emphasis, links, and code blocks. + + + +## Collaboration practices + + + +1. **Review locally** before creating a PR. +2. **Validate your changes** if possible. For example, check the W&B App, run code samples with mock values, or run SDK commands locally. +3. **Create feature branches** for all work. +4. **Start with a draft PR** to prevent premature reviews or inadvertent merges. +5. **Write a clear PR description** including: + - What changed and why + - Links to relevant JIRA or GitHub issues + - Before/after comparison when applicable +6. **Wait for all tests to pass** before marking PR as ready for review. +7. **Let humans request reviews**. AI agents should not change a PR from a draft or merge PRs. The human working with the agent should verify that a PR is accurate, useful, and ready for review before requesting review. +8. **Let humans merge PRs**. AI agents should not merge a PR or enable auto-merge. The human working with the agent should verify that a PR has had adequate review and is published at an appropriate time. + + + + +## Security guidelines + + + +- Never include sensitive information (API keys, passwords, internal URLs). +- Be cautious about exposing infrastructure details. +- Review all contributions for potential security risks. +- Some runbooks require W&B employee access. + + + +## File handling + + + +- **Propose file organization thoughtfully**: When drafting, agents may suggest creating new files or editing existing ones based on available context. Humans should validate those architectural decisions before creating a draft PR, taking into consideration broader architectural patterns and team conventions that may not be visible in the immediate context. +- **Match surrounding style** when editing existing content. +- **Separate style refactors** from content changes. +- **Let humans initiate bulk style changes**. + + + +## Important context + + + +- This is a public repository, but some runbooks require W&B employee access. +- The repository uses Hugo as its static site generator. +- Documentation is available in multiple languages (English, Japanese, Korean). +- PR previews are generated using Cloudflare Pages. +- The main branch is protected and requires review before merge. +- Technical accuracy is required to ensure that the W&B documentation provides trustworthy and reliable information. + + diff --git a/.cursor/runbooks/README.md b/.cursor/runbooks/README.md new file mode 100644 index 0000000000..b2769dfc45 --- /dev/null +++ b/.cursor/runbooks/README.md @@ -0,0 +1,121 @@ +# Cursor runbooks for W&B documentation + +This directory contains task-specific runbooks formatted for optimal use with Cursor and other AI agents. These runbooks provide detailed, step-by-step instructions for complex or recurring tasks in the wandb/docs repository. + +## What are runbooks? + +Runbooks are structured guides that help AI agents (and humans) perform complex tasks consistently and correctly. They include: + +- Clear prerequisites and requirements +- Step-by-step procedures with exact commands +- Context about system limitations and constraints +- Common issues and their solutions +- Cleanup instructions to leave the system in a good state + +## Available runbooks + +### [test-github-action-changes.md](./test-github-action-changes.md) +Tests changes to GitHub Actions workflows using a fork, particularly for workflows that depend on Cloudflare Pages deployments. + +**Use cases:** +- Testing Dependabot PRs for action upgrades +- Verifying workflow functionality changes +- Debugging GitHub Actions issues +- Testing workflow changes before merging to main + +**Requirements**: W&B employee access + +### [TEMPLATE.md](./TEMPLATE.md) +A template for creating new runbooks. Copy this file and fill in the sections to create standardized, AI-friendly runbooks. + +## How to use these runbooks + +### For AI agents +1. Read the entire runbook before starting any task. +2. Gather all prerequisites from the user upfront. +3. Follow the steps exactly, adapting only where explicitly noted. +4. Pay attention to "Agent note" sections for special instructions. +5. Ask for clarification if any step is unclear. +6. Always complete the cleanup steps. + +### For humans +1. Provide the runbook to your AI agent as context. +2. Answer any prerequisite questions the agent asks. +3. Follow along as the agent executes the steps. +4. Complete any manual steps the agent cannot perform. +5. Verify the results match expected outcomes. + +## Creating new runbooks + +### When to create a runbook +Create a runbook when: +- A task requires multiple complex steps +- The task will be repeated in the future +- There are specific gotchas or edge cases to remember +- The task requires specific permissions or access +- You've just completed a complex task and want to capture the knowledge + +### Best practice: Agent-first authoring +The most effective runbooks are created immediately after completing a complex task. Ask your AI agent: + +> "Based on what we just did together, please create a runbook that would help another agent perform this same task in the future. Include all the context, gotchas, and workarounds we discovered." + +### Structure guidelines + +All runbooks follow this structure: +1. **Overview** - What the runbook accomplishes +2. **Requirements** - Access and permissions needed +3. **Prerequisites** - Information to gather from users +4. **Context and Constraints** - Important background and limitations +5. **Step-by-Step Process** - Detailed procedures +6. **Verification** - How to confirm success +7. **Troubleshooting** - Common issues and solutions +8. **Cleanup** - How to reset/clean up +9. **Summary Checklist** - Quick reference +10. **Additional Notes** - Extra context or tips + +### Formatting conventions + +- Use XML-like tags for major sections: `...` +- Include code blocks with appropriate language tags +- Use **Agent note:** for AI-specific instructions +- Provide exact commands and file paths +- Include placeholder syntax like `` for values to replace + +## Maintenance + +### Keeping runbooks current +- Test runbooks periodically to ensure they still work +- Update when tools, APIs, or processes change +- Add new troubleshooting items as issues are discovered +- Get feedback from agents and humans using the runbooks + +### Review process +1. Have an AI agent review new runbooks for clarity. +2. Test the runbook with a different agent. +3. Iterate based on confusion points or failures. +4. Update both .cursor and .ai versions if applicable. + +## Security considerations + +- **Access Requirements**: Clearly mark which runbooks require special access (e.g., W&B employee) +- **Sensitive Information**: Never include API keys, passwords, or internal URLs +- **Public Repository**: Remember these files are in a public repo +- **Temporary Changes**: Always include cleanup steps for any temporary modifications + +## Tips for effective runbooks + +1. **Be Explicit**: Don't assume knowledge; spell everything out +2. **Include Context**: Explain why steps are needed, not just what to do +3. **Anticipate Failures**: Include troubleshooting for common issues +4. **Test Thoroughly**: Run through the entire runbook before publishing +5. **Version Awareness**: Note any version-specific requirements +6. **Platform Differences**: Mention OS-specific variations if relevant + +## Getting help + +If you need help with runbooks: +1. Check the template for structure guidance. +2. Review existing runbooks for examples. +3. Ask an AI agent to review your draft. +4. Test with a fresh agent to find unclear parts. diff --git a/.cursor/runbooks/TEMPLATE.md b/.cursor/runbooks/TEMPLATE.md new file mode 100644 index 0000000000..92a3845d3e --- /dev/null +++ b/.cursor/runbooks/TEMPLATE.md @@ -0,0 +1,128 @@ +# [Task title] runbook + +## Overview + + +Brief description of what this runbook accomplishes and when to use it. + +**Note**: Any important context or limitations users should know upfront. + + +## Requirements + + +- [ ] Required system access (for example, W&B employee access) +- [ ] Required permissions (for example, repository write access) +- [ ] Required tools or dependencies + + +## Prerequisites + + +Information to gather from the user before starting: + +1. **[Required info 1]** - Why it's needed +2. **[Required info 2]** - Why it's needed +3. **[Optional info]** - When/why it might be needed + + +## Context and constraints + + +### System/tool limitations +- Limitation 1 and how it affects the task +- Limitation 2 and workarounds if any + +### Important background +- Key background information +- Common gotchas or edge cases +- Security considerations + + +## Step-by-step process + + +### Step 1: [First major step] +Description of what this step accomplishes. + +```bash +# Example commands +command --with-flags +``` + +**Expected result**: What should happen after this step. + +**Agent note**: Special instructions for AI agents, such as: +- When to ask the user for clarification +- Fallback procedures if lacking permissions +- How to handle common variations + +### Step 2: [Second major step] +Description and any decision points. + +[Continue with remaining steps...] + + +## Verification + + +### Expected outcomes +- ✓ Success indicator 1 +- ✓ Success indicator 2 +- ✗ Common failure indicator and what it means + +### How to verify success +1. Check that... +2. Confirm that... +3. Test by... + + +## Troubleshooting + + +### Issue: [Common problem 1] +- **Symptoms**: How this issue manifests +- **Cause**: Why it happens +- **Solution**: Step-by-step fix + +### Issue: [Common problem 2] +- **Symptoms**: Description +- **Cause**: Root cause +- **Solution**: How to resolve + + +## Cleanup + + +After completing the task: + +1. Remove any temporary files/branches +2. Reset any modified configurations +3. Document any permanent changes made + +```bash +# Example cleanup commands +git branch -D temp-branch-name +rm -f temporary-files +``` + + +## Summary checklist + + +- [ ] Met all requirements +- [ ] Gathered necessary information from user +- [ ] Completed step 1: [Brief description] +- [ ] Completed step 2: [Brief description] +- [ ] Verified results +- [ ] Cleaned up temporary resources +- [ ] Documented any permanent changes + + +## Additional notes + + +- Tips or additional context +- Links to related documentation +- When to use alternative approaches + diff --git a/.cursor/runbooks/test-github-action-changes.md b/.cursor/runbooks/test-github-action-changes.md new file mode 100644 index 0000000000..ac8f00af0f --- /dev/null +++ b/.cursor/runbooks/test-github-action-changes.md @@ -0,0 +1,284 @@ +# Testing GitHub Actions changes in wandb/docs + +## Overview + + +This runbook guides you through testing changes to GitHub Actions workflows in the wandb/docs repository, particularly the PR preview link generation workflows that depend on Cloudflare Pages deployments. + +**Note**: If you are testing changes to an action that doesn't depend on Cloudflare, adjust your interpretation of this runbook accordingly. + + +## Requirements + + +- [ ] **W&B employee access**: You must be a W&B employee with access to internal W&B systems +- [ ] **GitHub fork**: A personal fork of wandb/docs for testing workflow changes +- [ ] **Git push access**: Ability to push to either the fork or wandb/docs repository + + +## Prerequisites + + +Information to gather from the user before starting: + +1. **GitHub username** - Needed to identify their fork +2. **Fork status** - Confirm they have a fork of wandb/docs that can be used for testing +3. **Test scope** - What specific changes are being tested (dependency upgrade, functionality change, etc.) +4. **Push access** - Whether you can push directly to their fork or need to use wandb/docs + + +## Context and constraints + + +### Repository setup +- **Main repository**: `wandb/docs` (origin) +- **Fork for testing**: `/docs` (fork remote) +- **Important**: GitHub Actions in PRs always run from the base branch (main), not from the PR branch. +- **Cloudflare limitation**: Cloudflare Pages only builds for the main wandb/docs repository, not for forks. + +### Key workflows +1. `.github/workflows/pr-preview-links.yml` - Runs on PR open/sync +2. `.github/workflows/pr-preview-links-on-comment.yml` - Triggered by Cloudflare comments + +### Testing requirements +To test workflow changes, you must: +1. Sync the fork's main with the upstream main +2. Apply changes to the fork's main branch (not just a feature branch) +3. Override Cloudflare URLs since they won't generate for forks +4. Create a test PR with content changes to trigger the workflows + +### Agent limitations +- May not have direct push access to user's fork +- Will need to create temporary branches in wandb/docs for user to push + + +## Step-by-step process + + +### Step 1: Initial setup and information gathering + +First, gather required information: +```bash +# Ask the user for their GitHub username +# Example prompt: "What is your GitHub username for the fork we'll use for testing?" +``` + +Configure remotes: +```bash +# Check existing remotes +git remote -v + +# Add fork remote if missing +git remote add fork https://github.com//docs.git +``` + +**Expected result**: Both 'origin' (wandb/docs) and 'fork' (/docs) remotes configured. + +### Step 2: Prepare test branch + +Create a branch for the workflow changes: +```bash +# Start from latest main +git checkout main +git pull origin main + +# Create test branch with descriptive name +git checkout -b test-[description]-[date] +# Example: test-dependabot-upgrade-20250127 +``` + +**Agent note**: Use descriptive branch names that indicate what's being tested and when. + +### Step 3: Apply workflow changes + +Make the necessary changes to workflow files. Common scenarios: + +**For dependency upgrades**: +- Update version numbers in `uses:` statements +- Check both workflow files if the dependency is used in multiple places + +**For functionality changes**: +- Modify the workflow logic as needed +- Ensure changes are compatible with GitHub Actions syntax + +### Step 4: Add Cloudflare URL override + +Since Cloudflare won't build for forks, add temporary overrides. + +**For `pr-preview-links.yml`** (after URL extraction logic, around line ~220): +```javascript +// TEMPORARY OVERRIDE FOR FORK TESTING +// Since Cloudflare won't run on forks, use a hardcoded URL +if (!base && context.repo.owner === '') { // Replace + base = 'https://main.docodile.pages.dev'; + core.warning('Using temporary override URL for fork testing: ' + base); +} +``` + +**For `pr-preview-links-on-comment.yml`** (after URL extraction, around line ~126): +```javascript +// TEMPORARY OVERRIDE FOR FORK TESTING +// Since Cloudflare won't run on forks, use a hardcoded URL +if (!branchUrl && context.repo.owner === '') { // Replace + branchUrl = 'https://main.docodile.pages.dev'; + core.warning('Using temporary override URL for fork testing: ' + branchUrl); +} +``` + +**Agent note**: Replace `` with the actual GitHub username provided by the user. + +### Step 5: Commit and push to fork's main + +```bash +# Stage all changes +git add -A + +# Create descriptive commit +git commit -m "test: [Description of what you're testing] + +- Add Cloudflare URL override for fork testing +- [Other changes made]" + +# Push to fork's main branch +git push fork HEAD:main --force-with-lease +``` + +**Agent note**: If you cannot push to the fork directly: +1. Push to a temporary branch in wandb/docs +2. Provide the user with commands to push from there to their fork +3. Guide them through creating the PR +4. Remember to clean up the temporary branch afterward + +**Fallback instructions for users**: +```bash +# If agent created temp-branch-name in wandb/docs: +git fetch origin temp-branch-name +git push fork origin/temp-branch-name:main --force +``` + +### Step 6: Create test PR + +Create a branch with content changes to trigger workflows: +```bash +# Create new branch from updated fork main +git checkout -b test-pr-[description] + +# Add small content change +echo "" >> content/en/guides/quickstart.md + +# Commit and push +git add content/en/guides/quickstart.md +git commit -m "test: Add content change to trigger PR preview" +git push fork test-pr-[description] +``` + +**Agent note**: Direct user to create PR at: `https://github.com//docs/compare/main...test-pr-[description]` + +### Step 7: Monitor and verify + +Monitor the PR for expected behavior: +1. GitHub Actions bot should create initial comment with "Generating preview links..." +2. Workflow should complete without errors +3. Comment should update with preview links pointing to override URL + +Check Actions tab for any errors or warnings. + + +## Verification + + +### Expected outcomes +- ✓ Workflow completes successfully +- ✓ Preview comment is created and updated +- ✓ Links use the override URL (https://main.docodile.pages.dev) +- ✓ File categorization works (Added/Modified/Deleted/Renamed) +- ✓ No security warnings or exposed secrets + +### How to verify success +1. Check the Actions tab in the PR for green checkmarks +2. Verify the preview comment contains correct links +3. Review workflow logs for any warnings +4. Confirm file change detection is accurate + + +## Troubleshooting + + +### Issue: Permission denied when pushing to fork +- **Symptoms**: Git push fails with permission error. +- **Cause**: No write access to user's fork. +- **Solution**: Create temporary branch in wandb/docs and provide push instructions to user. + +### Issue: Workflows not triggering +- **Symptoms**: No GitHub Actions run after creating PR. +- **Cause**: Workflows run from base branch (main), not PR branch. +- **Solution**: Ensure changes are pushed to fork's main branch, not just feature branch. + +### Issue: Preview links not generating +- **Symptoms**: Comment stuck on "Generating preview links...". +- **Cause**: Missing or incorrect Cloudflare override. +- **Solution**: Verify override is added with correct username in owner check. + +### Issue: Changed files not detected +- **Symptoms**: Preview comment shows no files changed. +- **Cause**: Content changes not in tracked directories. +- **Solution**: Ensure changes are in content/, static/, assets/, or other tracked directories. + + +## Cleanup + + +After testing is complete: + +1. **Reset fork's main to match upstream**: + ```bash + git checkout main + git fetch origin + git reset --hard origin/main + git push fork main --force + ``` + +2. **Delete test branches**: + ```bash + # Delete local branches + git branch -D test-[description]-[date] test-pr-[description] + + # Delete remote branches if needed + git push fork --delete test-pr-[description] + ``` + +3. **Clean up any temporary branches in wandb/docs**: + ```bash + # If you created temporary branches + git push origin --delete temp-branch-name + ``` + +4. **Close test PR** (or ask user to close it) + + +## Summary checklist + + +- [ ] Asked user for GitHub username and fork details +- [ ] Configured both remotes (origin and fork) +- [ ] Applied workflow changes to both relevant files +- [ ] Added Cloudflare URL override with correct username +- [ ] Pushed changes to fork's main branch +- [ ] Created test PR with content changes +- [ ] Verified preview comment generated successfully +- [ ] Checked Actions logs for errors +- [ ] Reset fork's main branch after testing +- [ ] Cleaned up all temporary branches +- [ ] Closed test PR + + +## Additional notes + + +- The Cloudflare preview domain is `docodile.pages.dev` +- Branch previews normally use pattern: `https://[branch-name].docodile.pages.dev` +- The override uses the main branch preview as a stable fallback +- Always remove the Cloudflare override before merging to production +- This runbook is for W&B employees only due to internal system dependencies +- For non-Cloudflare workflows, skip steps 4 and adjust verification accordingly + diff --git a/.cursor/style.md b/.cursor/style.md new file mode 100644 index 0000000000..35087ef02d --- /dev/null +++ b/.cursor/style.md @@ -0,0 +1,398 @@ +# W&B documentation style guide + +This file contains detailed style guidelines for creating and editing W&B documentation. + +> **Tip**: To help save context tokens, agents do not automatically load prompts like this style guide. To ask your agent to load and use this style guide, prompt it with: "Read .cursor/style.md and follow these style guidelines for all documentation changes." + +## Style hierarchy + + +1. **Match existing content first**: When editing near existing content, match its style to maintain consistency. +2. **Google Developer Style Guide**: Primary reference for new content. +3. **Microsoft Style Guide**: Secondary reference when Google doesn't cover something. +4. **Chicago Manual of Style**: Tertiary reference for edge cases. + +### Critical: Checking existing style + +**Before making any edit**, agents should: +1. Read the entire file being edited to identify established patterns. +2. Check similar files in the same directory for conventions. +3. Look for patterns in: + - Heading formatting (sentence case vs title case) + - List punctuation (periods or not) + - Code example structure + - Term usage (for example, "W&B Run" vs "run") + - Voice and tense choices + +**Example**: If editing `/content/en/guides/track/log.md`, first check: +- How are headings capitalized in this file? +- How are similar concepts described in other files in `/content/en/guides/track/`? +- What code patterns are used in existing examples? + +**Remember**: Consistency within the existing corpus trumps perfect adherence to this style guide. Only apply new style rules when: +- Creating entirely new content +- Doing an explicit style refactor +- The existing style directly contradicts technical accuracy + + + +## Format specification + +### Markdown flavors + +**Documentation content** (`/content/` directory) uses **Hugo with Docsy theme**: +- Hugo's CommonMark implementation with specific extensions +- Docsy shortcodes for special features +- Hugo's built-in syntax highlighting +- **Important**: Not all GFM features work in Hugo content + +**Cursor configuration files** (like this one in `.cursor/`) use a hybrid format: +- Base format: GitHub Flavored Markdown for GitHub rendering +- Enhanced with: XML-like tags (`...`) for AI parsing +- Purpose: Human-readable on GitHub while being structured for AI agents + +Since Cursor config files are viewed on GitHub, they support GFM features like: +- Tables +- Task lists with `- [ ]` and `- [x]` +- Fenced code blocks with language highlighting +- Blockquotes with `>` + +### Technical formatting rules + +> **Note**: These expand on the basic formatting standards in [`rules.md`](rules.md#formatting-standards). + +- **Use spaces, not tabs**: 2 spaces per indentation level +- **Trim trailing whitespace**: Remove trailing spaces on all lines +- **Line endings**: Use LF (Unix-style) line endings +- **EditorConfig**: The repository includes an `.editorconfig` file that enforces these settings +- **Code blocks**: Use single backticks for inline `code` and triple backticks for code blocks with language identifiers + +## Detailed style rules + + +### Headings +- Use sentence case for all headings (capitalize only the first word and proper nouns). +- Keep headings concise and descriptive. +- Use imperative mood for task-based headings. +- Examples: + - ✓ "Configure your environment" + - ✓ "Get started with W&B" + - ✓ "Integrate with GitHub Actions" + - ✗ "Configuring Your Environment" + - ✗ "Getting Started with W&B" + - ✗ "Integrating With GitHub Actions" + + + + +### Product and feature names + +#### Company name +- Use "W&B" (not "Weights & Biases") in running text. +- Exception: Use full name in legal documents or first-time introductions to new audiences. +- **Avoid using "W&B" in headings**: Shorter headings are clearer, easier to scan, and better for SEO. When editing existing content, match the heading style already in use. For new content, omit "W&B" from headings unless necessary for disambiguation (for example, when comparing W&B features to other tools). +- **When uncertain about W&B terminology**: Check existing content for established patterns. If still unsure, add a TODO comment for human review: + ```html + + ``` + This approach prevents incorrect terminology while flagging items for review. + +#### Product name patterns +First mention on a page: +- "W&B Models" → subsequent mentions: "Models" +- "W&B Weave" → subsequent mentions: "Weave" +- "W&B Launch" → subsequent mentions: "Launch" +- "W&B Automations" → subsequent mentions: "Automations" + +#### Feature capitalization +Some features become lowercase after first mention: +- "W&B Run" → "run" (because it's an API object) +- "W&B Sweep" → "sweep" (because it's an API object) +- "W&B Report" → "report" (common noun usage) + +Special cases: +- "W&B artifact" - always lowercase, even on first mention (matches API naming) +- "W&B project" - always lowercase (common noun) + +#### Examples in context +- "Configure W&B Automations to monitor your runs. Automations can send alerts when specific conditions are met." +- "Create a W&B Run to track your experiment. The run captures metrics, system information, and outputs." +- "W&B artifacts help version your datasets. Each artifact is immutable once created." + + + + +### Voice and tone + +#### General guidelines +- **Direct and concise**: Get to the point quickly. +- **Second person and imperative mood**: Use imperative commands for instructions ("Configure the API key"). The "you" is implied in instructions and makes instructions more direct. "You" may occasionally be approriate for explanations and descriptions. +- **Active voice**: "Configure the API key" not "The API key should be configured". +- **Present tense**: Describe what happens, not what will happen. +- **Simple verbs**: "Use" not "Utilize", "Start" not "Initiate". + +#### Examples +Instructions (use imperative): +✓ "To configure authentication, set the API key." +✓ "Set an environment variable for the API key." +✗ "You should configure authentication by setting the API key." + +Explanations (use "you" explicitly): +✓ "You can track experiments with W&B." +✓ "When you run this code, W&B logs the metrics." +✓ "W&B tracks experiments." +✗ "Experiments will be tracked by W&B." +✗ "Experiments are tracked by W&B." + + + + +### Accessibility guidelines + +#### Emoji usage +**Never use emojis in documentation content**. They create multiple problems: +- Screen readers may announce them disruptively. +- Translation tools handle them inconsistently. +- Cultural interpretations vary. +- They don't display consistently across platforms. + +**Limited exceptions** (use sparingly): +- Examples of correct and incorrect examples together, such as in this style guide (✓/✗). +- Comparison matrixes. +- Specific cases when they add clarity without relying on color. + +**Prefer**: +- Plain text descriptions. +- Unicode symbols (✓) over emoji equivalents (✅). +- Clear, descriptive text over any symbol. + +#### Plain language +Replace complex terms and Latin phrases: +- ✓ "for example" → ✗ "e.g." +- ✓ "that is" → ✗ "i.e." +- ✓ "and so on" → ✗ "etc." +- ✓ "versus" → ✗ "vs." +- ✓ "through" → ✗ "via" + + + + +### Punctuation guidelines + +#### Quotes and apostrophes +Markdown is a plain text format. Always use straight quotes and apostrophes: +- ✓ `"straight quotes"` and `'apostrophes'` +- ✗ "curly quotes" and 'smart apostrophes' + +**Why**: Smart quotes can break code examples and cause parsing issues. They often creep in from copy-pasting from rich text editors. + +#### Simplify punctuation +Avoid in regular documentation text: +- Exclamation points (!) +- Semicolons (;) +- Em dashes (—) and en dashes (–). Use colons, commas, or parentheses instead. +- Complex inline lists with nested punctuation. +- Ellipses (...) and horizontal ellipsis characters (…), except in code examples to indicate omitted code. + + > **Note**: Ellipses are acceptable in code blocks to show omitted sections: + ```python + def train_model(config): + # Setup code here + ... # Additional training logic + return model + ``` + +#### Lists +- Use sentence case for all list items. +- **Include periods for most list items**. This is a tech writing convention. +- **Use colons for definition-style lists**: When a list item introduces sub-items or provides an explanation, use a colon instead of a hyphen. +- Include periods for: + - Complete sentences + - Long phrases (more than 5-7 words) + - Items with explanatory text or descriptions + - Any item that contains multiple words beyond simple labels +- Omit periods only for very short fragments (2-3 words that are simple labels). + +Examples of proper formatting: +- ✓ **Bold term**: Explanation of what this means. +- ✓ **Another term**: Its definition or description. +- ✗ **Wrong format** - Should use colon, not hyphen. + +Examples of when to use periods: +- ✓ "Configure your API key." (complete sentence) +- ✓ "Repository access for creating branches and pushing changes." (long phrase) +- ✓ "Python 3.8 or higher with pip installed." (detailed requirement) +- ✓ "Code examples with proper syntax highlighting." (descriptive item) +- ✓ "API reference" (short fragment - no period) +- ✓ "Quick links" (short label - no period) + + + + +### Code and technical terms + +#### Inline code +Use backticks for: +- File names: `config.yaml` +- Commands: `wandb login` +- Code elements: `wandb.init()` +- Directory paths: `runbooks/` +- Function names: `log_metrics()` +- Variable names: `api_key` + +#### Code blocks +Always specify the language: +```python +# Python code +with wandb.init(project="my-project") as run: + run.log({"accuracy": 0.95}) +``` + +```bash +# Shell commands +wandb login +pip install wandb +``` + +```yaml +# YAML configuration +project: my-project +entity: my-team +``` + +#### Showing Markdown or HTML code as code +To render Markdown or HTML as code in the output, surround it with backticks. + +- **Inline**: Use single backticks to show inline code like `**bold text**` or `[link text](url)` +- **Block**: Use triple backticks (fences) with language identifier: + ````markdown + ```html +
+

This HTML will be shown as code, not rendered.

+
+ ``` + ```` + Or for Markdown: + ````markdown + ```markdown + ## This heading won't render + - This list item won't render + - It will all appear as code + ``` + ```` + +#### Code example best practices +1. **Follow public API patterns** from https://docs.wandb.ai/ref/python/ +2. **Use context managers** for `wandb.init()` +3. **Include imports** and minimal setup +4. **Make examples runnable** without additional context +5. **Test when possible** to ensure correctness +6. **Avoid placeholder names** like "foo" or "bar" - use meaningful examples + + + + +### Text formatting standards + +#### Emphasis +- `**Bold**` for UI elements: "Click the **New Project** button" +- `*Italics*` (or `_italics_`) sparingly for introducing new terms +- `` `Code` `` for technical terms, commands, and code elements +- Avoid combining multiple formatting styles. + +#### Links +- Use descriptive link text. +- ✓ "See the [API reference](link) for details" +- ✗ "Click [here](link) for more information" +- ✗ "The API reference is available [at this link](link)" + +#### File paths +- Use forward slashes even for Windows paths. +- Start with `/` for absolute paths +- Omit leading `/` for relative paths. +- Use backticks: `/home/user/project` or `data/dataset.csv` + + + + +### Common documentation patterns + +#### Prerequisites sections +**Common heading**: "Prerequisites" is the most common pattern in existing docs, though "Requirements", "Getting started", and "Before you begin" also appear. + +```markdown +## Prerequisites + +Before you begin, ensure you have: +- Python 3.8 or higher installed. +- A W&B account. [Sign up here](https://wandb.ai/signup) if needed. +- Basic familiarity with machine learning concepts. +``` + +#### Step-by-step instructions +```markdown +## Get started + +Follow these steps to set up W&B: + +1. **Install the W&B library**: + ```bash + pip install wandb + ``` + +2. **Authenticate your account**: + ```bash + wandb login + ``` + +3. **Initialize your first run**: + ```python + import wandb + + with wandb.init(project="quickstart") as run: + run.log({"metric": 1.0}) + ``` +``` + +#### Troubleshooting sections +```markdown +## Troubleshooting + +### Issue: Authentication fails + +**Symptoms**: Error message "Failed to authenticate" + +**Solution**: +1. Verify your API key is correct. +2. Check your internet connection. +3. Ensure your firewall allows HTTPS traffic to api.wandb.ai. +``` + + + + +### Writing tips for AI agents + +1. **Check surrounding content first**: Match the style of nearby content. +2. **Be consistent within a page**: Don't switch styles mid-document. +3. **Avoid over-formatting**: Clean, simple formatting is best. +4. **Think about scanning**: Users scan documentation, make it easy with clear headings and lists. +5. **Include examples**: Show, don't just tell. +6. **Test your instructions**: Can someone follow them without additional context? +7. **Review for accessibility**: Would this work for non-native English speakers? +8. **Keep sentences short**: Aim for 20 words or less when possible. +9. **One idea per paragraph**: Don't pack too much into a single paragraph. +10. **Use transition words**: Help readers follow your logic with words like "First", "Next", "However". + + + +## Important reminders + + +- This style guide supplements but doesn't replace the main rules in `rules.md` +- When in doubt, consistency trumps perfection. +- In general, separate style changes from content changes. +- Prioritize technical accuracy, clarity, and user success over strict style adherence. +- Check existing content for established patterns before creating new ones. + + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 76dc934746..a362dcd9cc 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,6 +2,7 @@ +