Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
302 lines (209 loc) · 12 KB

CONTRIBUTING.md

File metadata and controls

302 lines (209 loc) · 12 KB

Contributing to the DevRel Foundation Site

Welcome to the DevRel Foundation.

We're excited to have you contribute to our mission.

Table of Contents

Getting Started

The DevRel Foundation website serves as the central hub for information about our community, hosting resources, blog content, and wayfinding to our working groups and projects. All contributions should align with our mission to provide valuable, vendor-neutral resources for the Developer Relations community.

Prerequisites

Before contributing, please ensure you have:

Code of Conduct

All contributors are expected to adhere to the DevRel Foundation Code of Conduct. By participating in this project, you agree to maintain a respectful, inclusive, and collaborative environment.

Ways to Contribute

Blog Posts

Share insights, tutorials, and perspectives on Developer Relations Foundation topics that highlight the value that the community and resources provide.

See more details below about contributing blog posts because we are looking for blog posts that support the mission of the foundation. A good litmus test for the content we seek is that it references something created for the DevRel Foundation.

Bug Reports

Found an issue with the website? Report it through a GitHub Issue to make sure we're aware.

Feature Requests

Suggest new features or improvements to enhance the site's functionality. This is a volunteer project so should set expectations accordingly. Reporting an issue is still helpful to understand what is valuable, building it is divine if you have the skill and time.

Documentation

Help improve our documentation, guides, and resources. If you are confused by anything you encounter, that is likely a good opportunity to ask questions and then improve upon it for everybody who comes along later.

Design & UX

Contribute to the visual design and user experience of the site.

Code Contributions

Help develop new features, fix bugs, or improve the site's technical implementation.

Blog Contribution Guidelines

You may be interested in contributing to our community blog but any contributions must be in alignment with our mission and the open-source spirit of the foundation we belong.

Here's what you need to know:

Content We Welcome

Blog posts should:

  • ✅ Focus on Developer Relations Foundation best practices, frameworks, or insights.
  • ✅ Be applicable to our community personas.
  • ✅ Provide practical value to DevRel professionals as a resource. We want solutions not just questions and opinions.
  • ✅ Share knowledge about DevRel and Linux Foundation resources and projects. Consider making your contribution to a project first before writing a blog post about it.
  • ✅ Present vendor-neutral perspectives and solutions.
  • ✅ Include original insights, case studies, or research.

Content We Don't Publish

We will not publish:

  • ❌ Job postings or recruitment content unless it is about a DevRel Foundation resource.
  • ❌ Backlink farming or SEO-focused content.
  • ❌ Promoted events without broader community value.
  • ❌ Content primarily advertising third-party commercial products.
  • ❌ Personal opinions without broader applicability or incorporation into foundation resources.
  • ❌ Content that violates our Code of Conduct.

Blog Post Structure

All blog posts must include frontmatter with the following fields:

---
title: "Your Blog Post Title"
excerpt: "A brief description (1-2 sentences) that will appear in listings"
author: "@your-github-username"
date: "YYYY-MM-DD"
category: "exec|early-ic|pro-lead|exec"
tags: ["tag1", "tag2", "tag3"]
---

Field Descriptions:

  • title: Clear, descriptive title (recommended: 60 characters or less)
  • excerpt: Brief summary for social sharing and listings
  • author: Your GitHub username (prefixed with @)
  • date: Publication date in YYYY-MM-DD format
  • category: Primary audience (exec, dev, marketing, community, product)
  • tags: 2-5 relevant tags for categorization

Content Guidelines

Writing Style

  • Write in a clear, accessible manner
  • Use active voice where possible
  • Include practical examples and actionable insights
  • Structure content with clear headings and subheadings
  • Keep paragraphs concise and scannable

Attribution and Sources

  • Properly cite all sources and references
  • Include links to relevant foundation resources where applicable
  • Give appropriate credit to community members and organizations
  • Avoid claiming ownership of community-wide ideas or practices

Images and Media

  • Use high-quality, relevant images
  • Ensure you have rights to use any images included
  • Optimize images for web (recommended: under 500KB)
  • Include descriptive alt text for accessibility
  • Store images in /static/images/blog/ directory

Blog Submission Process

  1. Fork the Repository: Create a fork of the site repository

  2. Create a New Branch:

    git checkout -b blog/your-github-username

  3. Create Your Blog Post:

    • Add your markdown file to /src/blog/
    • Use the naming convention: YYYY-MM-DD-your-post-slug.md
    • Include all required frontmatter fields and please match the date

  4. Add Images (if applicable):

    • Place images in /static/images/blog/
    • Reference them in your post as /images/blog/your-image.png

Avoid third-party image hosting, include it directly in the repository.

  1. Test Locally: Run the development server to ensure your post renders correctly

Corrections may be necessary, but understand that it can be a burden and we are volunteers should there be multiple review cycles.

  1. Submit Pull Request:
    • Push your changes to your fork
    • Create a pull request against the main repository
    • Include a clear description of your contribution

Blog Review

All blog posts go through a community review process:

  1. Community Review: Anyone can provide feedback and suggestions on your pull request
  2. Leadership Approval: At least one foundation leader must approve the content
  3. Technical Review: Ensure the post renders correctly and follows our formatting standards
  4. Final Approval: Once approved, your post will be merged and published

Review Criteria

Posts are evaluated based on:

  • Alignment with foundation values and mission
  • Relevance and value to the DevRel community
  • Technical accuracy and clarity
  • Vendor neutrality and independence
  • Originality and uniqueness of insights

Feedback and Revisions

If changes are requested:

  • Reviewers will provide specific, constructive feedback
  • Authors can update their pull requests with revisions
  • Additional review rounds may be necessary for complex changes

Publication Timeline

  • Standard Timeline: 5-10 business days from submission to publication
  • Expedited Review: Available for time-sensitive content (contact site maintainers)
  • Publication Date: Posts are typically published immediately upon approval

Content Guidelines

Inclusivity and Accessibility

  • Use inclusive language that welcomes all community members
  • Avoid jargon without proper explanation
  • Include alt text for images
  • Use proper heading structure for screen readers
  • Consider diverse perspectives and experiences

Technical Standards

  • Code examples should be tested and functional
  • Include language specifications for code blocks
  • Provide context for technical concepts
  • Link to official documentation where appropriate

Community Standards

  • Respect different viewpoints and approaches
  • Encourage constructive discussion
  • Avoid inflammatory or divisive language
  • Focus on practical solutions and shared learning

Examples

Here are a few examples to add clarity to the framing for stories we're looking for.

OK: These are the five metrics that I think every developer program should track...

Better: The DRF working group agreed that the top five metrics from the Metrics Index that every developer program should track...

OK: We had a birds of a feather at this really cool event and discussed some of the biggest challenges in devrel today...

Better: After a birds of a feather discussion, we've improved the Persona Library to highlight some of the key learnings on strategies to reach developer communities in collaboration with sales and marketing teams better...

OK: Create videos that developers actually want to watch

Better: The DRF Tools Catalog Tutorials has a new entry for YouTube aimed at helping create compelling content. Here are some of the top tips and then review the full tutorial for a deeper dive in how to create that content...

Cross-Posting Policy

We encourage cross-posting content to amplify diverse voices:

  • Timing: Cross-posts must be published to our platform within 7 days of original publication
  • Attribution: Include links to the original post if published elsewhere first
  • Coordination: Contact maintainers if you need a specific publication window
  • Originality: Content published elsewhere more than 7 days prior may be rejected

Disclaimer

All blog posts include the following disclaimer:

"This blog post represents the viewpoint of its author(s) and does not necessarily reflect an official position or perspective of the DevRel Foundation or any subsidiary working group. Authors' current workplace or affiliated products, if mentioned, are disclosed for transparency."

Development Contributions

  1. Check Existing Issues: Look for related issues or create a new one to discuss your contribution
  2. Fork and Branch: Create a descriptive branch for your changes
  3. Make Changes: Implement your contribution following our coding standards
  4. Test: Ensure all tests pass and the site builds correctly
  5. Submit PR: Create a pull request with a clear description

Development Setup

To run the site locally for development:

1. Clone the Repository

git clone https://github.com/DevRel-Foundation/site.git
cd site

2. Install Dependencies

npm install

3. Start Development Server

npm run dev -- --open

The site will be available at http://localhost:5173

4. Build for Production

npm run build

5. Preview Production Build

npm run preview

All PRs will get a Netlify preview and URL so that it can be shared and tested before merge.

Support

Need help with your contribution?

Questions?

If you have questions about contributing or need clarification on any guidelines:

  1. Search existing GitHub Issues
  2. Ask in our Discord community
  3. Contact us at info@dev-rel.org

Thank you for contributing to the DevRel Foundation! Your participation helps strengthen our community and advance the professional practice of Developer Relations worldwide.

This contributing guide is subject to updates as our community and projects evolve. Contributors will be notified of significant changes through our usual communication channels.