Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
420 lines (308 loc) · 13 KB

CONTRIBUTING.md

File metadata and controls

420 lines (308 loc) · 13 KB

Contributing to SpecOps

Thank you for your interest in contributing to SpecOps! This project is built on the principle that legacy modernization is a shared challenge, and collaboration makes everyone more effective.

Table of Contents

Ways to Contribute

SpecOps welcomes many types of contributions, and you don't need to be a developer or have access to legacy systems to help:

📚 Documentation Contributions

  • Clarify existing documentation
  • Add examples and use cases
  • Fix typos and improve readability
  • Translate documentation
  • Create video tutorials or guides
  • Write blog posts about your SpecOps experience

💡 Instruction Set Contributions

  • Share AI agent instruction sets (skills) for legacy platforms
  • Contribute COBOL, PL/I, RPG, or other legacy language comprehension skills
  • Add domain-specific knowledge (benefits, tax, licensing, etc.)
  • Improve existing instruction sets based on your experience
  • Document patterns and anti-patterns you've discovered

🔧 Tooling and Infrastructure

  • Create templates for specifications
  • Build verification checklists
  • Develop automation scripts
  • Integrate with CI/CD pipelines
  • Create GitHub Actions or workflows
  • Build visualization tools for specifications

📊 Experience Reports

  • Share lessons learned from applying SpecOps
  • Document what worked and what didn't
  • Describe your specific context and adaptations
  • Provide metrics and outcomes
  • Write case studies (anonymized if necessary)

🎓 Educational Content

  • Create training materials
  • Develop workshops or presentations
  • Write tutorials for specific tools or techniques
  • Create onboarding guides for new team members
  • Share best practices from your organization

🐛 Issue Reporting

  • Report unclear or confusing documentation
  • Suggest improvements to the methodology
  • Identify gaps in the documentation
  • Request new instruction sets or examples

💬 Community Building

  • Answer questions from other users
  • Share your SpecOps implementations
  • Organize meetups or working groups
  • Facilitate cross-government collaboration
  • Help newcomers get started

Getting Started

For First-Time Contributors

  1. Read the core documentation

  2. Look for "good first issue" labels

    • Browse open issues marked as beginner-friendly
    • These are designed to help you learn the contribution process

  3. Join the conversation

    • Introduce yourself in discussions
    • Ask questions if anything is unclear
    • Share what you're interested in contributing

  4. Start small

    • Fix a typo, improve a sentence, or add a clarifying example
    • This helps you learn the workflow before tackling larger contributions

For Experienced Contributors

  1. Identify high-value contributions

    • Review open issues and prioritize high-impact items
    • Look for gaps in documentation or instruction sets
    • Consider what would have helped you when you started

  2. Collaborate with others

    • Coordinate with other contributors on larger efforts
    • Share draft work early to get feedback
    • Help review and improve others' contributions

  3. Think about reusability

    • Focus on contributions that benefit multiple organizations
    • Generalize solutions when possible
    • Document prerequisites and assumptions clearly

Contribution Guidelines

Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers and help them succeed
  • Focus on what's best for the community
  • Show empathy and kindness
  • Be patient with questions and different perspectives

Quality Standards

Documentation should be:

  • Clear and concise
  • Accessible to non-technical stakeholders when appropriate
  • Well-structured with proper headings and navigation
  • Free of jargon or with jargon clearly defined
  • Actionable with specific steps or examples

Instruction sets should be:

  • Well-documented with clear purpose and scope
  • Tested with actual AI coding agents
  • Specific about which tools/platforms they work with
  • Versioned with changelog information
  • Generalized enough to be useful across organizations

Experience reports should be:

  • Honest about both successes and challenges
  • Specific about context and constraints
  • Anonymized if necessary to protect sensitive information
  • Focused on lessons learned and recommendations
  • Backed by data when available

Types of Contributions

1. Instruction Sets

Instruction sets are one of the most valuable and reusable contributions to SpecOps.

What makes a good instruction set contribution:

  • Clear purpose: Explicitly state what the instruction set helps AI agents do
  • Platform-specific details: Specify which AI tools/platforms it's designed for (Claude, GitHub Copilot, etc.)
  • Testing documentation: Describe how you tested it and what results you saw
  • Examples: Include before/after examples showing the instruction set in action
  • Limitations: Document known limitations or edge cases
  • Prerequisites: List any required knowledge or setup

How to contribute an instruction set:

  1. Create a new file in docs/instruction-sets/ using the template below
  2. Test the instruction set with at least one AI coding agent
  3. Document your testing process and results
  4. Submit a pull request with clear description

Template:

# [Instruction Set Name]

## Purpose
[What this instruction set helps AI agents accomplish]

## Target Platform
[Which AI tools this works with: Claude Projects, GitHub Copilot, etc.]

## Instructions
[The actual instruction set text]

## Testing
[How you tested this and what results you observed]

## Examples
[Before/after examples or sample outputs]

## Known Limitations
[Edge cases or scenarios where this doesn't work well]

## Version History
- v1.0 (YYYY-MM-DD): Initial version

2. Documentation Improvements

We welcome all documentation improvements, from typo fixes to major restructuring.

Small improvements:

  • Fix typos, grammar, or formatting
  • Add clarifying examples
  • Improve link accuracy
  • Update outdated information

Larger improvements:

  • Reorganize sections for better flow
  • Add new sections covering gaps
  • Create visual diagrams or flowcharts
  • Write additional guides or tutorials

How to contribute:

  1. Identify what needs improvement
  2. Make your changes
  3. Submit a pull request explaining the improvement

3. Experience Reports

Share what you learned applying SpecOps in your organization.

What to include:

  • Context: What type of system, organization size, timeline
  • Approach: Which parts of SpecOps you used and how you adapted them
  • Outcomes: What worked well, what was challenging
  • Metrics: Quantitative results if available (time saved, errors caught, etc.)
  • Lessons learned: Key takeaways and recommendations
  • Would you do it again: Honest assessment

How to contribute:

  1. Write your experience report as a markdown file
  2. Anonymize sensitive information if needed
  3. Place in docs/case-studies/ directory
  4. Submit a pull request

4. Tool Integrations

Help others integrate SpecOps with their existing tools and workflows.

Examples:

  • GitHub Actions workflows for specification validation
  • Templates for specification repositories
  • Integration guides for specific AI coding tools
  • Scripts for automating specification generation
  • CI/CD pipeline examples

How to contribute:

  1. Create your integration/tool
  2. Document setup and usage clearly
  3. Include examples and troubleshooting tips
  4. Place in tools/ directory with README
  5. Submit a pull request

5. Templates and Examples

Provide reusable templates that make SpecOps easier to adopt.

Examples:

  • Specification document templates
  • Verification checklist templates
  • Stakeholder review forms
  • Project planning templates
  • Sprint/iteration planning guides

How to contribute:

  1. Create your template
  2. Add documentation explaining when and how to use it
  3. Include a filled-out example
  4. Place in templates/ directory
  5. Submit a pull request

Submitting Contributions

Pull Request Process

  1. Fork the repository

    • Create your own fork of the spec-ops repository
    • Clone it to your local machine

  2. Create a branch

    • Use a descriptive branch name: add-cobol-instruction-set or fix-methodology-typos
    • Keep branches focused on a single contribution

  3. Make your changes

    • Follow the style and formatting of existing documents
    • Add your contribution following the guidelines above
    • Test any instruction sets or tools

  4. Commit your changes

    • Write clear commit messages
    • Reference any related issues

  5. Submit a pull request

    • Provide a clear title and description
    • Explain what you're contributing and why
    • Link to any relevant issues or discussions
    • Be open to feedback and iteration

Review Process

  • A maintainer will review your pull request
  • They may suggest changes or ask questions
  • Once approved, your contribution will be merged
  • You'll be credited as a contributor

Style Guidelines

Markdown formatting:

  • Use ATX-style headers (# not underlines)
  • Include table of contents for documents longer than 200 lines
  • Use code blocks with language specification
  • Use relative links for internal references
  • Include alt text for images

Writing style:

  • Use clear, direct language
  • Define acronyms on first use
  • Write in present tense
  • Use active voice when possible
  • Keep paragraphs focused and concise

File naming:

  • Use UPPERCASE for top-level documents (MANIFESTO.md)
  • Use kebab-case for subdirectory files (cobol-comprehension.md)
  • Use descriptive, searchable names

Community Standards

Respectful Collaboration

  • Assume good intent: Give others the benefit of the doubt
  • Be constructive: Focus on improvements, not just criticism
  • Welcome newcomers: Remember everyone is learning
  • Share credit: Acknowledge others' contributions
  • Stay on topic: Keep discussions focused on SpecOps

Sharing Across Organizations

  • Prioritize reusability: Make contributions useful to others
  • Respect confidentiality: Don't share proprietary information
  • Generalize solutions: Abstract away organization-specific details
  • Document context: Help others understand when your contribution applies
  • Encourage adaptation: Make it easy for others to modify your work

Licensing and Attribution

  • All contributions are released under the MIT License
  • By contributing, you agree to license your work under these terms
  • You retain copyright to your contributions
  • Your contributions will be attributed to you in commit history
  • We maintain a contributors list to recognize participation

Questions and Support

Where to Ask Questions

  • General questions: Open a GitHub Discussion
  • Bug reports: Open a GitHub Issue
  • Documentation clarification: Comment on the relevant document or open an issue
  • Contribution ideas: Open a GitHub Discussion to gauge interest

Getting Help

If you're stuck or need guidance:

  1. Check existing documentation and issues
  2. Ask in GitHub Discussions
  3. Reach out to maintainers
  4. Join community channels (when available)

Response Time

  • We aim to respond to questions within a week
  • Complex contributions may take longer to review
  • Please be patient—this is a community-driven project

Recognition

We value all contributions, large and small. Contributors are recognized through:

  • GitHub contributor badges
  • Attribution in commit history
  • Mentions in release notes for significant contributions
  • Community spotlight for exceptional contributions

Thank You!

Every contribution makes SpecOps more useful for government agencies and organizations working to modernize legacy systems. Whether you're sharing an instruction set, fixing a typo, or writing an experience report, you're helping preserve institutional knowledge and improve outcomes for the public.

Your contributions matter. Thank you for being part of this community.

Getting Started Checklist

Ready to contribute? Here's your checklist:

  • Read the Manifesto and Methodology
  • Review existing issues and discussions
  • Decide what you want to contribute
  • Fork the repository
  • Make your contribution following these guidelines
  • Test your contribution (for instruction sets and tools)
  • Submit a pull request with clear description
  • Respond to feedback and iterate

Welcome to the SpecOps community! 🚀