sarman/dgx-spark-playbooks
1
0
Fork 0
mirror of https://github.com/NVIDIA/dgx-spark-playbooks.git synced 2026-04-22 18:13:52 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Adding contributing guidelines

Browse Source 
Signed-off-by: Margaret Zhang <margaretz@margaretz-mlt.client.nvidia.com>
This commit is contained in:
Margaret Zhang 2025-10-28 15:14:32 -04:00
parent af0833dd53
commit a254444d57
3 changed files with 447 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
CONTRIBUTING.md Normal file
View File

@ -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 <local-branch>:<remote-branch>
```
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 <your@email.com>
```
* 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! 🚀

257
PLAYBOOK-GUIDELINES.md Normal file
View File

@ -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.

3
README.md
View File

@ -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.
- [LICENSE](LICENSE) for licensing information.