From a254444d570ea2922b3ee36b27be7635af756836 Mon Sep 17 00:00:00 2001 From: Margaret Zhang Date: Tue, 28 Oct 2025 15:14:32 -0400 Subject: [PATCH] Adding contributing guidelines Signed-off-by: Margaret Zhang --- CONTRIBUTING.md | 189 ++++++++++++++++++++++++++++++ PLAYBOOK-GUIDELINES.md | 257 +++++++++++++++++++++++++++++++++++++++++ README.md | 3 +- 3 files changed, 447 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 PLAYBOOK-GUIDELINES.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0d753e5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,189 @@ +# Contributing to DGX Spark Playbooks + +Thank you for your interest in contributing to the DGX Spark Playbooks! This repository provides step-by-step guides for AI/ML workloads on NVIDIA DGX Spark devices, and we welcome contributions from the community. + +## Table of Contents + +- [Getting Started](#getting-started) +- [Types of Contributions](#types-of-contributions) +- [Issue Tracking](#issue-tracking) +- [Playbook Guidelines](#playbook-guidelines) +- [License](#license) + - [Pull Requests](#pull-requests) + - [Signing Your Work](#signing-your-work) +- [Questions?](#questions) + + +## Types of Contributions + +We welcome the following types of contributions: + +### 🆕 New Playbooks +- Step-by-step guides for AI/ML frameworks not yet covered +- Optimization techniques for existing frameworks +- Integration guides between multiple tools +- Performance benchmarking tutorials + +### 📝 Documentation Improvements +- Corrections to existing playbooks +- Additional troubleshooting sections +- Enhanced examples and code snippets +- Better explanations of complex concepts + +### 🐛 Bug Fixes +- Corrections to incorrect commands or configurations +- Updates for deprecated software versions +- Fixes to broken links or references + +### 🔧 Infrastructure Improvements +- Templates for new playbooks +- CI/CD improvements +- Repository organization enhancements + +## Issue Tracking + +We use GitHub Issues to track bugs, feature requests, and general discussions about the DGX Spark Playbooks. + +### Before Opening an Issue + +1. **Search existing issues** to avoid duplicates +2. **Test on the latest version** of DGX Spark software +3. **Gather system information** (DGX Spark version, hardware config, etc.) + +### Bug Reports + +When reporting bugs, please include: + +```markdown +**Playbook**: [Name of the affected playbook] +**DGX Spark Version**: [e.g., 24.10] +**Hardware**: [GPU model, memory, etc.] +**Steps to Reproduce**: +1. Step one +2. Step two +3. ... + +**Expected Behavior**: [What should happen] +**Actual Behavior**: [What actually happens] +**Error Messages**: [Full error messages and logs] +**Additional Context**: [Screenshots, related issues, etc.] +``` + +### Feature Requests + +For new playbook requests or enhancements: + +```markdown +**Feature Type**: [New Playbook / Enhancement / Integration] +**Framework/Tool**: [Name and version] +**Use Case**: [Why this would be valuable] +**Priority**: [High / Medium / Low] +**Additional Context**: [Links, examples, related work] +``` + +### Issue Labels + +We use the following labels to categorize issues: + +- `bug`: Something isn't working correctly +- `enhancement`: New feature or improvement request +- `documentation`: Documentation improvements +- `new-playbook`: Request for a new playbook +- `help-wanted`: Community contributions welcome +- `good-first-issue`: Suitable for newcomers +- `duplicate`: Duplicate of existing issue +- `invalid`: Issue is not valid or off-topic +- `wontfix`: Issue will not be addressed + + +## Playbook Guidelines + +For detailed information on creating high-quality playbooks, please refer to [PLAYBOOK-GUIDELINES.md](PLAYBOOK-GUIDELINES.md). This document covers: + +- Directory structure requirements +- README.md templates and content standards +- Code and script guidelines +- Asset organization +- Testing requirements +- Maintenance guidelines + +## License + +By contributing to this project, you agree that your contributions will be licensed under the same license as the project. See [LICENSE](LICENSE) for details. + +#### Pull Requests +Developer workflow for code contributions is as follows: + +1. Developers must first [fork](https://help.github.com/en/articles/fork-a-repo) the [upstream](https://github.com/nvidia/dgx-spark-playbooks) DGX Spark Playbook repository. + +2. Git clone the forked repository and push changes to the personal fork. + + ```bash +git clone https://github.com/YOUR_USERNAME/YOUR_FORK.git TensorRT +# Checkout the targeted branch and commit changes +# Push the commits to a branch on the fork (remote). +git push -u origin : + ``` + +3. Once the code changes are staged on the fork and ready for review, a [Pull Request](https://help.github.com/en/articles/about-pull-requests) (PR) can be [requested](https://help.github.com/en/articles/creating-a-pull-request) to merge the changes from a branch of the fork into a selected branch of upstream. + * Exercise caution when selecting the source and target branches for the PR. + Note that versioned releases of TensorRT OSS are posted to `release/` branches of the upstream repo. + * Creation of a PR creation kicks off the code review process. + * Atleast one TensorRT engineer will be assigned for the review. + * While under review, mark your PRs as work-in-progress by prefixing the PR title with [WIP]. + +4. Since there is no CI/CD process in place yet, the PR will be accepted and the corresponding issue closed only after adequate testing has been completed, manually, by the developer and/or TensorRT engineer reviewing the code. + + +#### Signing Your Work + +* We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license. + + * Any contribution which contains commits that are not Signed-Off will not be accepted. + +* To sign off on a commit you simply use the `--signoff` (or `-s`) option when committing your changes: + ```bash + $ git commit -s -m "Add cool feature." + ``` + This will append the following to your commit message: + ``` + Signed-off-by: Your Name + ``` + +* Full text of the DCO: + + ``` + Developer Certificate of Origin + Version 1.1 + + Copyright (C) 2004, 2006 The Linux Foundation and its contributors. + 1 Letterman Drive + Suite D4700 + San Francisco, CA, 94129 + + Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. + ``` + + ``` + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or + + (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or + + (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. + + (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. + ``` + +## Questions? + +If you have questions about contributing, please: +1. Check existing [GitHub Discussions](../../discussions) +2. Review this contributing guide thoroughly +3. Open a new discussion with the "Contributing" category +4. Tag maintainers if you need urgent assistance + +Thank you for helping make DGX Spark more accessible to the AI/ML community! 🚀 diff --git a/PLAYBOOK-GUIDELINES.md b/PLAYBOOK-GUIDELINES.md new file mode 100644 index 0000000..bc94308 --- /dev/null +++ b/PLAYBOOK-GUIDELINES.md @@ -0,0 +1,257 @@ +# Playbook Guidelines + +This document provides detailed guidelines for creating high-quality playbooks for the DGX Spark Playbooks repository. + +## Table of Contents + +- [Structure Requirements](#structure-requirements) +- [README.md Template](#readmemd-template) +- [Content Standards](#content-standards) +- [Code and Script Guidelines](#code-and-script-guidelines) +- [Asset Guidelines](#asset-guidelines) +- [Testing Requirements](#testing-requirements) +- [Maintenance Guidelines](#maintenance-guidelines) + +## Structure Requirements + +Each playbook must follow this directory structure: + +``` +community/your-playbook-name/ +├── README.md # Main playbook content +├── assets/ # Supporting files +│ ├── images/ # Screenshots, diagrams +│ ├── configs/ # Configuration files +│ ├── scripts/ # Shell scripts, Python files +│ └── examples/ # Sample code, datasets +``` + +### Directory Naming Convention + +- Use lowercase with hyphens for directory names +- Be descriptive but concise (e.g., `flux-finetuning`, `multi-agent-chatbot`) +- Avoid abbreviations unless they are widely recognized +- Match the primary technology or framework name + +## README.md Template + +Your playbook's `README.md` should include: + +```markdown +# Your Playbook Title + +Brief description of what this playbook accomplishes. + +## Prerequisites + +- Hardware requirements +- Software dependencies +- Required access/accounts + +## Overview + +Detailed explanation of the technology and use case. + +## Instructions + +### Step 1: Setup Environment +[Detailed instructions with commands] + +### Step 2: Install Dependencies +[More instructions] + +### Step 3: Configuration +[Configuration steps] + +### Step 4: Running the Application +[Execution instructions] + +## Verification + +How to verify the setup is working correctly. + +## Troubleshooting + +Common issues and their solutions. + +## Next Steps + +- Additional resources +- Related playbooks +- Advanced configurations + +## Resources + +- Official documentation links +- Community forums +- Related repositories +``` + +## Content Standards + +### ✅ Do's + +- **Be comprehensive**: Include all necessary steps from start to finish +- **Test thoroughly**: Verify all commands work on a clean DGX Spark system +- **Use clear language**: Write for users with varying experience levels +- **Include verification**: Provide ways to confirm each step worked +- **Add troubleshooting**: Document common issues and solutions +- **Keep updated**: Ensure compatibility with latest software versions +- **Use consistent formatting**: Follow markdown best practices +- **Provide context**: Explain why each step is necessary +- **Include performance expectations**: Document expected completion times +- **Add security considerations**: Highlight any security implications + +### ❌ Don'ts + +- **Assume knowledge**: Don't skip "obvious" steps +- **Use relative paths**: Always use absolute paths where possible +- **Include secrets**: Never commit API keys, passwords, or tokens +- **Copy without testing**: All content must be validated on DGX Spark +- **Use deprecated methods**: Always use current best practices +- **Skip error handling**: Always include error scenarios +- **Use unclear pronouns**: Be specific about what "it" or "this" refers to +- **Mix different approaches**: Stick to one method per playbook + +### Writing Style + +- Use active voice ("Run the command" vs "The command should be run") +- Write in second person ("you will..." not "one should...") +- Use present tense for instructions +- Be consistent with terminology throughout +- Use numbered lists for sequential steps +- Use bullet points for non-sequential items + +## Code and Script Guidelines + +### General Requirements + +- All scripts must be tested on DGX Spark +- Include comprehensive comments +- Use error handling and validation +- Follow language-specific style guides +- Include requirements/dependencies files +- Document any system modifications + +## Asset Guidelines + +### Images + +- **Format**: Use PNG for screenshots, SVG for diagrams when possible +- **Resolution**: Maximum 1920px width, optimize for web viewing +- **Naming**: Use descriptive names (e.g., `login-screen.png`, `architecture-diagram.svg`) +- **Alt text**: Include meaningful descriptions for accessibility +- **Size**: Keep under 500KB when possible, compress if necessary + +### Scripts + +- Include shebang lines (`#!/bin/bash`, `#!/usr/bin/env python3`) +- Set appropriate execute permissions (`chmod +x script.sh`) +- Use `.sh` extension for shell scripts +- Include usage comments at the top +- Test on DGX Spark before committing + +### Configuration Files + +- Provide both template (`.template`) and example (`.example`) versions +- Remove sensitive information from examples +- Include validation scripts where applicable +- Document all required and optional parameters + +### Example Code and Datasets + +- Keep datasets small (< 10MB) or provide download instructions +- Include data licenses and attribution +- Provide sample inputs and expected outputs +- Test all example code before including + +## Testing Requirements + +### Validation Checklist + +Before submitting a playbook, ensure: + +- [ ] **Clean installation test**: Tested on a fresh DGX Spark system +- [ ] **All commands work**: Every command executes without errors +- [ ] **Links are valid**: All URLs and file references work +- [ ] **Prerequisites listed**: All dependencies documented +- [ ] **Verification steps**: Ways to confirm success at each stage +- [ ] **Troubleshooting tested**: Common issues documented and solutions verified +- [ ] **Performance noted**: Expected execution times documented +- [ ] **Resource usage**: Memory/disk requirements specified + +### Test Environment + +- Use a clean DGX Spark installation +- Document the specific DGX Spark software version used +- Test with minimal privileges (don't assume root access) +- Verify network connectivity requirements +- Test with different hardware configurations if applicable + +### Documentation Testing + +- [ ] Spelling and grammar check +- [ ] Markdown formatting validation +- [ ] Image loading verification +- [ ] Code syntax highlighting works +- [ ] Internal links function correctly +- [ ] External links are accessible + +## Maintenance Guidelines + +### Version Compatibility + +- Test with latest DGX Spark software releases +- Update deprecated commands and methods +- Maintain compatibility matrices when applicable +- Document breaking changes clearly + +### Content Updates + +- Review playbooks quarterly for accuracy +- Update software versions and download links +- Refresh screenshots when UI changes +- Validate external resources remain available + +### Community Feedback + +- Respond to issues and questions promptly +- Incorporate user feedback and improvements +- Track common problems for FAQ updates +- Monitor performance and optimization opportunities + +### Deprecation Process + +When a playbook becomes outdated: + +1. Add deprecation notice to the README +2. Provide migration path to newer alternatives +3. Set timeline for removal (minimum 6 months) +4. Update main repository README +5. Archive the playbook with clear historical context + +## Quality Assurance + +### Pre-Submission Review + +Contributors should self-review using this checklist: + +- [ ] Follows directory structure requirements +- [ ] Uses provided README template +- [ ] Meets all content standards +- [ ] Includes proper error handling +- [ ] Assets are optimized and properly named +- [ ] All testing requirements met +- [ ] Documentation is clear and complete + +### Continuous Improvement + +- Gather user feedback through GitHub issues +- Monitor playbook usage and success rates +- Update based on new DGX Spark features +- Benchmark performance improvements +- Share best practices across playbooks + +--- + +For questions about these guidelines, please open a GitHub Discussion or contact the maintainers. diff --git a/README.md b/README.md index 99df497..ceeae27 100644 --- a/README.md +++ b/README.md @@ -59,5 +59,4 @@ Each playbook includes prerequisites, step-by-step instructions, troubleshooting ## License See: -- [LICENSE](LICENSE) for licensing information. -- [LICENSE-3rd-party](LICENSE-3rd-party) for third-party licensing information. \ No newline at end of file +- [LICENSE](LICENSE) for licensing information. \ No newline at end of file