Repository navigation
Add CONTRIBUTING.md and STYLEGUIDE.md - #10
Conversation
CONTRIBUTING.md covers the process: publishing with example.yaml, the docs preview and sync pull requests, and the rules for the docs repository. STYLEGUIDE.md covers the conventions: README structure, docs components, links, code blocks, example code, launch badges, example.yaml, and an upleveling checklist. tools/docs-render/README.md becomes maintainer notes for the converter. Co-authored-by: openhands <openhands@all-hands.dev>
Docs preview✅ Docs preview is ready: https://allhandsai-cookbook-preview-pr-10.mintlify.site
Docs PR: OpenHands/docs#889 (draft preview; never merged, closes with this PR). |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Excellent documentation PR. The guides are well-structured, clearly written, and provide actionable guidance for contributors.
Changes:
- Adds CONTRIBUTING.md covering the contribution process and publishing workflow
- Adds STYLEGUIDE.md with comprehensive conventions for writing examples
- Updates README.md and cookbook.yaml to reference the new documentation
- Refactors tools/docs-render/README.md to focus on converter maintenance
Validation:
✅ All internal links and anchors verified to exist
✅ Referenced files and workflows exist
✅ Commands are correct for uv-based project
✅ Documentation is internally consistent and complete
✅ No material issues found
[RISK ASSESSMENT]
Risk Level: LOW
- Documentation-only change with no code modifications
- Improves contribution quality and consistency
- No security, compatibility, or functional concerns
Verdict: APPROVED. This PR successfully establishes clear contribution guidelines and style standards that will benefit all future contributors.
Was this automated review useful? React with 👍 or 👎 to this review to help us measure review quality.
Workflow run: https://github.com/OpenHands/enterprise-cookbook/actions/runs/37167278629
2 participants
Why
Each example now has to read well on GitHub and render as a docs page, and the remaining examples are about to be brought up to the standard set by
command-blacklist(#8). This splits the guidance into two files.CONTRIBUTING.mdis the process: publishing withexample.yaml, what the preview and sync pull requests in OpenHands/docs do, what a failingdocs-previewmeans, and whycookbook/in the docs repository is never edited by hand.STYLEGUIDE.mdis the conventions: README structure with standard section names, when to use each docs component, links, code blocks, script flags, launch badges,example.yaml, and an upleveling checklist to work through for each example.For general writing style, the style guide points to the docs site's own guide rather than restating it. That guide sets Title Case for first- and second-level headings and calls for tabs when there are alternative approaches. The authoring rules that were in
tools/docs-render/README.mdmoved into these files, so that README is now notes for maintaining the converter.A few rules choose between conventions the examples currently disagree on:
command-blacklist), and 5 use "Usage".OH_API_BASEand 3 readOH_API_URL.example.yamltitles are in sentence case.Where an example disagrees, the guide says to follow the guide; those examples get fixed when they're upleveled. The checklist also covers launch badges: every badge in the repository still encodes
github:jpshackelford/oh-examplesin its base64 payload.Validation
pre-commit,pytest,npm test,npm run check). Every relative link and#anchoracross the four Markdown files resolves. The new external links return 200, exceptdocs.openhands.dev/cookbook, which goes live when docs(cookbook): sync from OpenHands/enterprise-cookbook docs#884 merges.mainruleset. Theexample.yamlrules, card icons and CLI defaults match the converter code. The flag/environment-variable table matches what the existing scripts read.This PR was drafted by an AI agent on behalf of the user.
@jpshackelford can click here to continue refining the PR