From dcb40ed4d756d3d4f31a485a0b6fac145bb8066a Mon Sep 17 00:00:00 2001 From: Jeffrey Paul Date: Wed, 17 Sep 2025 15:43:40 -0500 Subject: [PATCH 1/6] Restructure site navigation by project lifecycle - Create nav-outline.md with proposed navigation structure - Update index.md with lifecycle-oriented navigation sections: - Starting or Releasing a Project - Maintaining, Supporting, and Enhancing - Growing and Sustaining a Project - References and Resources - Add section landing pages for each major category - Map existing content to new structure - Maintain backward compatibility with existing URLs This restructuring makes it easier for first-time open source releasers and long-time maintainers to find guidance relevant to their situation. --- growing/index.md | 68 +++++++++++++++++++++++++++++++ index.md | 67 ++++++++++++------------------- maintaining/index.md | 65 ++++++++++++++++++++++++++++++ nav-outline.md | 96 ++++++++++++++++++++++++++++++++++++++++++++ references/index.md | 58 ++++++++++++++++++++++++++ starting/index.md | 61 ++++++++++++++++++++++++++++ 6 files changed, 374 insertions(+), 41 deletions(-) create mode 100644 growing/index.md create mode 100644 maintaining/index.md create mode 100644 nav-outline.md create mode 100644 references/index.md create mode 100644 starting/index.md diff --git a/growing/index.md b/growing/index.md new file mode 100644 index 0000000..d3b587b --- /dev/null +++ b/growing/index.md @@ -0,0 +1,68 @@ +--- +page: growing +title: Growing and Sustaining a Project +nav: Growing +group: navigation +weight: 4 +layout: default +subnav: + - title: Governance Models + tag: governance + - title: Community Recognition + tag: community-recognition + - title: Roadmaps & Planning + tag: roadmaps + - title: Sponsorships / Funding + tag: sponsorships + - title: Succession Planning + tag: succession + - title: Sunsetting/Archiving Projects + tag: sunsetting +updated: 25 November 2019 +--- + +
+
+

Growing and Sustaining a Project

+

Strategies for mature projects and long-term community sustainability.

+
+ +
+

Who is this section for?

+
    +
  • Maintainers of mature, growing projects
    • +
  • Communities looking to establish governance
    • +
  • Projects seeking long-term sustainability
    • +
  • Organizations managing multiple open source projects
    • +
+
+ +
+

What you'll learn

+
    +
  • Establishing effective governance models
    • +
  • Recognizing and rewarding community contributions
    • +
  • Creating and maintaining project roadmaps
    • +
  • Exploring funding and sponsorship opportunities
    • +
  • Planning for maintainer succession
    • +
  • Gracefully sunsetting or archiving projects
    • +
+
+ +
+

Growth Strategies

+

Key areas for project growth and sustainability:

+
    +
  1. Establish clear governance
    2. +
  2. Recognize contributors
    3. +
  3. Plan with roadmaps
    4. +
  4. Explore funding options
    5. +
  5. Plan for the future
    6. +
+
+ +
+

Note

+

Some sections in this category are still being developed. The existing content provides a foundation, and we're working on expanding guidance for governance, funding, succession planning, and project sunsetting.

+
+
diff --git a/index.md b/index.md index ddcb8ee..127448d 100644 --- a/index.md +++ b/index.md @@ -36,63 +36,48 @@ updated: 25 November 2019
-

Releasing Code

+

Starting or Releasing a Project

-

Maintenance Process

+

Maintaining, Supporting, and Enhancing

-

Community

- -
- -
-

GitHub Process

+

Growing and Sustaining a Project

-

Testing

+

References and Resources

diff --git a/maintaining/index.md b/maintaining/index.md new file mode 100644 index 0000000..9576cb0 --- /dev/null +++ b/maintaining/index.md @@ -0,0 +1,65 @@ +--- +page: maintaining +title: Maintaining, Supporting, and Enhancing a Project +nav: Maintaining +group: navigation +weight: 3 +layout: default +subnav: + - title: CHANGELOG Standards + tag: changelog + - title: Issue Triage & Labeling + tag: issues + - title: Pull Request Guidelines + tag: pull-requests + - title: Continuous Integration / Testing + tag: ci-testing + - title: Documentation Standards + tag: documentation + - title: Security Handling + tag: security + - title: Communication Best Practices + tag: communication +updated: 25 November 2019 +--- + +
+
+

Maintaining, Supporting, and Enhancing a Project

+

Ongoing maintenance practices for established open source projects.

+
+ +
+

Who is this section for?

+
    +
  • Project maintainers managing active repositories
    • +
  • Teams supporting existing open source projects
    • +
  • Contributors looking to improve project processes
    • +
+
+ +
+

What you'll learn

+
    +
  • Maintaining proper changelogs and versioning
    • +
  • Effective issue triage and labeling strategies
    • +
  • Pull request review and management processes
    • +
  • Setting up continuous integration and testing
    • +
  • Documentation maintenance and standards
    • +
  • Security vulnerability handling
    • +
  • Community communication best practices
    • +
+
+ +
+

Key Areas

+

Focus on these critical maintenance areas:

+
    +
  1. Keep changelogs up to date
    2. +
  2. Organize issues and PRs effectively
    3. +
  3. Streamline pull request workflows
    4. +
  4. Maintain robust CI/CD
    5. +
  5. Handle security responsibly
    6. +
+
+
diff --git a/nav-outline.md b/nav-outline.md new file mode 100644 index 0000000..96f318a --- /dev/null +++ b/nav-outline.md @@ -0,0 +1,96 @@ +# Proposed Navigation Structure + +This document outlines the proposed restructuring of the Open Source Best Practices site navigation to align with the project lifecycle. + +## A. Starting or Releasing a Project + +Content for first-time open source releasers and new project maintainers: + +- **README.md best practices** → Maps to: `community.md` (README section) +- **License file** → Maps to: `releasing.md` (Licensing section) +- **Contribution guidelines** → Maps to: `community.md` (Contributing Guidelines section) +- **Code of Conduct** → Maps to: `community.md` (Code of Conduct section) +- **Semantic Versioning & Release Tags** → Maps to: `releasing.md` (Changelog section) +- **Initial Repo Setup (branches, labels, templates)** → Maps to: `github-process.md` (Issue and PR labels, Branching sections) + +## B. Maintaining, Supporting, and Enhancing a Project + +Content for ongoing project maintenance and community management: + +- **CHANGELOG standards** → Maps to: `releasing.md` (Changelog section) +- **Issue triage & labeling** → Maps to: `github-process.md` (Issue and PR labels section) +- **Pull Request guidelines** → Maps to: `github-process.md` (Issue and PR labels section) +- **Continuous Integration / Testing** → Maps to: `github-process.md` (Continuous Integration section) + `testing.md` +- **Documentation standards** → Maps to: `github-process.md` (Documentation section) +- **Security handling** → Maps to: `releasing.md` (Security section) +- **Communication best practices** → Maps to: `maintaining.md` (Issue and PR Management section) + +## C. Growing and Sustaining a Project + +Content for mature projects and community growth: + +- **Governance models** → **MISSING** - Needs to be created +- **Community recognition** → Maps to: `releasing.md` (Team and Credit Management section) +- **Roadmaps & planning** → Maps to: `github-process.md` (Milestones section) +- **Sponsorships / funding** → **MISSING** - Needs to be created +- **Succession planning** → **MISSING** - Needs to be created +- **Sunsetting/archiving projects** → **MISSING** - Needs to be created + +## D. References and Resources + +Supporting materials and external resources: + +- **Recommended tools & services** → **MISSING** - Needs to be created +- **External standards (SPDX, OSI, SemVer)** → **MISSING** - Needs to be created +- **Example repositories** → **MISSING** - Needs to be created + +## Content Mapping Summary + +### Existing Content (Maps to new structure): +- `index.md` (Introduction) → Stays as homepage +- `releasing.md` → Maps to sections A and B +- `maintaining.md` → Maps to section B +- `community.md` → Maps to section A +- `github-process.md` → Maps to sections A and B +- `testing.md` → Maps to section B + +### Missing Content (Needs to be created): +- Governance models +- Sponsorships/funding +- Succession planning +- Sunsetting/archiving projects +- Recommended tools & services +- External standards +- Example repositories + +## Proposed URL Structure + +- `/starting/` - Landing page for new project guidance +- `/starting/readme/` - README best practices +- `/starting/license/` - License file guidance +- `/starting/contributing/` - Contribution guidelines +- `/starting/code-of-conduct/` - Code of Conduct +- `/starting/versioning/` - Semantic Versioning & Release Tags +- `/starting/repo-setup/` - Initial Repo Setup + +- `/maintaining/` - Landing page for ongoing maintenance +- `/maintaining/changelog/` - CHANGELOG standards +- `/maintaining/issues/` - Issue triage & labeling +- `/maintaining/pull-requests/` - Pull Request guidelines +- `/maintaining/ci-testing/` - Continuous Integration / Testing +- `/maintaining/documentation/` - Documentation standards +- `/maintaining/security/` - Security handling +- `/maintaining/communication/` - Communication best practices + +- `/growing/` - Landing page for project growth +- `/growing/governance/` - Governance models +- `/growing/community-recognition/` - Community recognition +- `/growing/roadmaps/` - Roadmaps & planning +- `/growing/sponsorships/` - Sponsorships / funding +- `/growing/succession/` - Succession planning +- `/growing/sunsetting/` - Sunsetting/archiving projects + +- `/references/` - Landing page for resources +- `/references/tools/` - Recommended tools & services +- `/references/standards/` - External standards +- `/references/examples/` - Example repositories diff --git a/references/index.md b/references/index.md new file mode 100644 index 0000000..5679ec1 --- /dev/null +++ b/references/index.md @@ -0,0 +1,58 @@ +--- +page: references +title: References and Resources +nav: References +group: navigation +weight: 5 +layout: default +subnav: + - title: Recommended Tools & Services + tag: tools + - title: External Standards (SPDX, OSI, SemVer) + tag: standards + - title: Example Repositories + tag: examples +updated: 25 November 2019 +--- + +
+
+

References and Resources

+

Supporting materials, tools, and external resources for open source projects.

+
+ +
+

Who is this section for?

+
    +
  • Anyone looking for tools and services
    • +
  • Projects needing to comply with standards
    • +
  • Developers seeking example implementations
    • +
  • Maintainers researching best practices
    • +
+
+ +
+

What you'll find

+
    +
  • Curated lists of recommended tools and services
    • +
  • Information about external standards and compliance
    • +
  • Example repositories demonstrating best practices
    • +
  • Links to authoritative resources and documentation
    • +
+
+ +
+

Quick Reference

+

Essential resources for open source projects:

+ +
+ +
+

Note

+

This section is currently being developed. We're compiling comprehensive lists of tools, services, standards, and example repositories to help you implement these best practices effectively.

+
+
diff --git a/starting/index.md b/starting/index.md new file mode 100644 index 0000000..1c5348e --- /dev/null +++ b/starting/index.md @@ -0,0 +1,61 @@ +--- +page: starting +title: Starting or Releasing a Project +nav: Starting +group: navigation +weight: 2 +layout: default +subnav: + - title: README.md Best Practices + tag: readme + - title: License File + tag: license + - title: Contribution Guidelines + tag: contributing + - title: Code of Conduct + tag: code-of-conduct + - title: Semantic Versioning & Release Tags + tag: versioning + - title: Initial Repo Setup + tag: repo-setup +updated: 25 November 2019 +--- + +
+
+

Starting or Releasing a Project

+

Essential guidance for first-time open source releasers and new project maintainers.

+
+ +
+

Who is this section for?

+
    +
  • Developers releasing their first open source project
    • +
  • Teams starting new open source initiatives
    • +
  • Anyone looking to establish proper project foundations
    • +
+
+ +
+

What you'll learn

+
    +
  • How to create effective README files
    • +
  • Choosing and implementing proper licensing
    • +
  • Setting up contribution guidelines and code of conduct
    • +
  • Understanding semantic versioning and release management
    • +
  • Initial repository setup and configuration
    • +
+
+ +
+

Quick Start

+

If you're new to open source, start with these essential steps:

+
    +
  1. Create a comprehensive README
    2. +
  2. Choose and add a license
    3. +
  3. Set up contribution guidelines
    4. +
  4. Add a code of conduct
    5. +
  5. Configure your repository
    6. +
+
+
From 6d77cf6937024119de8572c3a3e7b14287431c93 Mon Sep 17 00:00:00 2001 From: Jeffrey Paul Date: Wed, 17 Sep 2025 15:50:55 -0500 Subject: [PATCH 2/6] Add section intro stub pages for new navigation - Create reusable stub-template.md for consistent section landing pages - Enhance all section landing pages with standardized structure: - 'Who this is for' - Clear audience targeting - 'What you'll find here' - High-level content overview - 'Next steps' - Actionable links to child pages - Update content to match template requirements: - Starting: Focus on first-time open source releasers - Maintaining: Target active project maintainers - Growing: Address mature project needs - References: Provide quick access to tools and standards These stub pages provide clear orientation for newcomers and help users quickly identify the most relevant practices for their situation. --- growing/index.md | 22 ++++++------- maintaining/index.md | 20 ++++++------ references/index.md | 23 +++++++------- starting/index.md | 20 ++++++------ stub-template.md | 76 ++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 116 insertions(+), 45 deletions(-) create mode 100644 stub-template.md diff --git a/growing/index.md b/growing/index.md index d3b587b..665ca8c 100644 --- a/growing/index.md +++ b/growing/index.md @@ -28,29 +28,27 @@ updated: 25 November 2019
-

Who is this section for?

+

Who this is for

    -
  • Maintainers of mature, growing projects
    • -
  • Communities looking to establish governance
    • +
  • Project leads looking to grow their community
    • +
  • Maintainers seeking to scale governance
  • Projects seeking long-term sustainability
    • -
  • Organizations managing multiple open source projects
-

What you'll learn

+

What you'll find here

    -
  • Establishing effective governance models
    • -
  • Recognizing and rewarding community contributions
    • -
  • Creating and maintaining project roadmaps
    • -
  • Exploring funding and sponsorship opportunities
    • -
  • Planning for maintainer succession
    • -
  • Gracefully sunsetting or archiving projects
    • +
  • Community engagement and recognition
    • +
  • Roadmaps and project planning
    • +
  • Governance structures
    • +
  • Funding and sponsorship options
    • +
  • Sunsetting projects responsibly
-

Growth Strategies

+

Next steps

Key areas for project growth and sustainability:

  1. Establish clear governance
    2. diff --git a/maintaining/index.md b/maintaining/index.md index 9576cb0..111c79f 100644 --- a/maintaining/index.md +++ b/maintaining/index.md @@ -30,29 +30,27 @@ updated: 25 November 2019
    -

    Who is this section for?

    +

    Who this is for

      -
    • Project maintainers managing active repositories
      • +
    • Maintainers of active projects who want to improve quality
    • Teams supporting existing open source projects
      • -
    • Contributors looking to improve project processes
      • +
    • Contributors looking to streamline contributions and set expectations
    -

    What you'll learn

    +

    What you'll find here

      -
    • Maintaining proper changelogs and versioning
      • -
    • Effective issue triage and labeling strategies
      • -
    • Pull request review and management processes
      • -
    • Setting up continuous integration and testing
      • -
    • Documentation maintenance and standards
      • -
    • Security vulnerability handling
      • +
    • How to manage issues and pull requests
      • +
    • Setting up CI/testing workflows
      • +
    • Writing changelogs and documentation
      • +
    • Handling security and support
    • Community communication best practices
    -

    Key Areas

    +

    Next steps

    Focus on these critical maintenance areas:

    1. Keep changelogs up to date
      2. diff --git a/references/index.md b/references/index.md index 5679ec1..0cfda8e 100644 --- a/references/index.md +++ b/references/index.md @@ -22,33 +22,32 @@ updated: 25 November 2019
      -

      Who is this section for?

      +

      Who this is for

        -
      • Anyone looking for tools and services
        • -
      • Projects needing to comply with standards
        • -
      • Developers seeking example implementations
        • -
      • Maintainers researching best practices
        • +
      • Anyone who wants quick access to tools, standards, and examples
        • +
      • Projects needing to comply with industry standards
        • +
      • Developers seeking example implementations beyond the main guides
      -

      What you'll find

      +

      What you'll find here

        -
      • Curated lists of recommended tools and services
        • -
      • Information about external standards and compliance
        • -
      • Example repositories demonstrating best practices
        • +
      • Recommended tooling (CI providers, automation bots)
        • +
      • Industry standards (SPDX, OSI, SemVer)
        • +
      • Example repositories with strong practices
      • Links to authoritative resources and documentation
      -

      Quick Reference

      +

      Next steps

      Essential resources for open source projects:

      - +
    diff --git a/starting/index.md b/starting/index.md index 1c5348e..f577b8f 100644 --- a/starting/index.md +++ b/starting/index.md @@ -28,27 +28,27 @@ updated: 25 November 2019
    -

    Who is this section for?

    +

    Who this is for

      -
    • Developers releasing their first open source project
      • -
    • Teams starting new open source initiatives
      • +
    • People planning to publish their first repo
      • +
    • Teams who want a checklist before announcing a new open source project
    • Anyone looking to establish proper project foundations
    -

    What you'll learn

    +

    What you'll find here

      -
    • How to create effective README files
      • -
    • Choosing and implementing proper licensing
      • -
    • Setting up contribution guidelines and code of conduct
      • -
    • Understanding semantic versioning and release management
      • -
    • Initial repository setup and configuration
      • +
    • How to set up a repo for success
      • +
    • Choosing a license and adding a Code of Conduct
      • +
    • Writing a clear README and contribution guidelines
      • +
    • Versioning and release basics
      • +
    • Initial repository configuration and best practices
    -

    Quick Start

    +

    Next steps

    If you're new to open source, start with these essential steps:

    1. Create a comprehensive README
      2. diff --git a/stub-template.md b/stub-template.md new file mode 100644 index 0000000..f0f4b01 --- /dev/null +++ b/stub-template.md @@ -0,0 +1,76 @@ +# Stub Page Template for Open Source Best Practices + +This template provides a consistent structure for section landing pages across the Open Source Best Practices site. + +## Template Structure + +```markdown +--- +page: [section-name] +title: [Section Title] +nav: [Navigation Title] +group: navigation +weight: [number] +layout: default +subnav: + - title: [First Child Page] + tag: [tag-name] + - title: [Second Child Page] + tag: [tag-name] + - title: [Third Child Page] + tag: [tag-name] +updated: [date] +--- + +
      +
      +

      [Section Title]

      +

      [One-sentence summary for metadata and page description]

      +
      + +
      +

      Who this is for

      +
        +
      • [Brief description of primary audience]
        • +
      • [Secondary audience if applicable]
        • +
      • [Tertiary audience if applicable]
        • +
      +
      + +
      +

      What you'll find here

      +
        +
      • [High-level overview of first type of guide]
        • +
      • [High-level overview of second type of guide]
        • +
      • [High-level overview of third type of guide]
        • +
      • [High-level overview of fourth type of guide]
        • +
      • [High-level overview of fifth type of guide]
        • +
      +
      + +
      +

      Next steps

      +

      [Brief introduction to the next steps section]

      +
        +
      1. [Link to first child page]
        2. +
      2. [Link to second child page]
        3. +
      3. [Link to third child page]
        4. +
      +
      +
      +``` + +## Usage Guidelines + +1. **Replace bracketed placeholders** with actual content +2. **Keep descriptions concise** - aim for 1-2 sentences per bullet point +3. **Use plain language** - avoid jargon when possible +4. **Link to existing content** where available, or create placeholder links for future content +5. **Maintain consistent tone** - helpful, encouraging, and practical + +## Section-Specific Notes + +- **Starting**: Focus on first-time open source releasers +- **Maintaining**: Target active project maintainers +- **Growing**: Address mature project needs +- **References**: Provide quick access to tools and standards From 1bd5b563ab4f3f113fde644d553a1157ef968576 Mon Sep 17 00:00:00 2001 From: Jeffrey Paul Date: Wed, 17 Sep 2025 16:06:37 -0500 Subject: [PATCH 3/6] Migrate practice pages into new lifecycle sections - Create content-migration-mapping.csv documenting the migration plan - Move practice pages to appropriate lifecycle sections: - Starting: community.md, releasing.md - Maintaining: maintaining.md, github-process.md, testing.md - Growing: (index.md only, content references existing sections) - References: (index.md only, content references existing sections) - Update all internal links to point to new file locations - Update front matter for moved files to reflect new navigation structure - Preserve repository management files (CODE_OF_CONDUCT.md, CONTRIBUTING.md, CREDITS.md, LICENSE.md, README.md) in root directory - Update navigation links in section landing pages This migration improves content discoverability by organizing practices according to the project lifecycle while maintaining all existing functionality. --- content-migration-mapping.csv | 12 ++++++++++++ growing/index.md | 4 ++-- index.md | 30 +++++++++++++++--------------- maintaining/github-process.md | 33 +++++++++++++++++++++++++++++++++ maintaining/index.md | 10 +++++----- maintaining/maintaining.md | 29 +++++++++++++++++++++++++++++ maintaining/testing.md | 21 +++++++++++++++++++++ starting/community.md | 21 +++++++++++++++++++++ starting/index.md | 10 +++++----- starting/releasing.md | 33 +++++++++++++++++++++++++++++++++ 10 files changed, 176 insertions(+), 27 deletions(-) create mode 100644 content-migration-mapping.csv create mode 100644 maintaining/github-process.md create mode 100644 maintaining/maintaining.md create mode 100644 maintaining/testing.md create mode 100644 starting/community.md create mode 100644 starting/releasing.md diff --git a/content-migration-mapping.csv b/content-migration-mapping.csv new file mode 100644 index 0000000..df749b9 --- /dev/null +++ b/content-migration-mapping.csv @@ -0,0 +1,12 @@ +Current Title,Current File Path,Proposed Section,New File Path,Notes +Introduction,index.md,Homepage,/index.md,Stays as homepage +Community,community.md,Starting,/starting/community.md,README, Code of Conduct, Contributing Guidelines +Releasing Code,releasing.md,Starting,/starting/releasing.md,Naming, Licensing, Client Permissions, Choosing Tools, Accessibility, Security, Release Process, Changelog, Team and Credit Management +Maintenance Process,maintaining.md,Maintaining,/maintaining/maintaining.md,Maintainers and Contributors, Issue and PR Management, WordPress.org Support, Tracking GitHub activity, Tracking WordPress.org activity, Version Control, WordPress and PHP Minimums +GitHub Process,github-process.md,Maintaining,/maintaining/github-process.md,Issue and PR labels, Milestones, Branching Merging and Deploying, Documentation, Support Levels, OpenGraph Image, Dependency Management, Coding Standards, Continuous Integration +Testing,testing.md,Maintaining,/maintaining/testing.md,Critical Flows and Test Cases, Code Coverage, E2E Testing +CODE_OF_CONDUCT.md,CODE_OF_CONDUCT.md,Repository Management,/,NOT MOVED - Repository management file +CONTRIBUTING.md,CONTRIBUTING.md,Repository Management,/,NOT MOVED - Repository management file +CREDITS.md,CREDITS.md,Repository Management,/,NOT MOVED - Repository management file +LICENSE.md,LICENSE.md,Repository Management,/,NOT MOVED - Repository management file +README.md,README.md,Repository Management,/,NOT MOVED - Repository management file diff --git a/growing/index.md b/growing/index.md index 665ca8c..8f0e023 100644 --- a/growing/index.md +++ b/growing/index.md @@ -52,8 +52,8 @@ updated: 25 November 2019

      Key areas for project growth and sustainability:

      1. Establish clear governance
        2. -
      2. Recognize contributors
        3. -
      3. Plan with roadmaps
        4. +
      4. Recognize contributors
        5. +
      5. Plan with roadmaps
      6. Explore funding options
      7. Plan for the future
      diff --git a/index.md b/index.md index 127448d..3127d6f 100644 --- a/index.md +++ b/index.md @@ -38,25 +38,25 @@ updated: 25 November 2019

      Starting or Releasing a Project

      Maintaining, Supporting, and Enhancing

      @@ -64,8 +64,8 @@ updated: 25 November 2019

      Growing and Sustaining a Project

    diff --git a/maintaining/maintaining.md b/maintaining/maintaining.md new file mode 100644 index 0000000..2a95ed3 --- /dev/null +++ b/maintaining/maintaining.md @@ -0,0 +1,29 @@ +--- +page: maintaining-maintaining +title: Maintenance Process +nav: Maintaining +group: navigation +weight: 3 +layout: default +subnav: + - title: Maintainers and Contributors + tag: maintainers-contributors + - title: Issue and PR Management + tag: issue-pr-mgmt + - title: WordPress.org Support + tag: dotorg-support + - title: Tracking GitHub activity + tag: slack-channel-github-activity + - title: Tracking WordPress.org activity + tag: slack-channel-dotorg-activity + - title: Version Control + tag: version-control + - title: WordPress and PHP Minimums + tag: wp-php-mins +updated: 11 July 2022 +--- + +
    + {% capture design %}{% include markdown/Maintaining.md %}{% endcapture %} + {{ design | markdownify }} +
    diff --git a/maintaining/testing.md b/maintaining/testing.md new file mode 100644 index 0000000..a7d7c1a --- /dev/null +++ b/maintaining/testing.md @@ -0,0 +1,21 @@ +--- +page: maintaining-testing +title: Testing +nav: Maintaining +group: navigation +weight: 3 +layout: default +subnav: + - title: Critical Flows and Test Cases + tag: critical-flows + - title: Code Coverage + tag: code-coverage + - title: E2E Testing + tag: e2e-testing +updated: 10 April 2024 +--- + +
    + {% capture design %}{% include markdown/Testing.md %}{% endcapture %} + {{ design | markdownify }} +
    diff --git a/starting/community.md b/starting/community.md new file mode 100644 index 0000000..4903125 --- /dev/null +++ b/starting/community.md @@ -0,0 +1,21 @@ +--- +page: starting-community +title: Community +nav: Starting +group: navigation +weight: 2 +layout: default +subnav: + - title: Readme + tag: readme + - title: Code of Conduct + tag: code-of-conduct + - title: Contributing Guidelines + tag: contributing +updated: 29 October 2019 +--- + +
    + {% capture php %}{% include markdown/Community.md %}{% endcapture %} + {{ php | markdownify }} +
    diff --git a/starting/index.md b/starting/index.md index f577b8f..555ad29 100644 --- a/starting/index.md +++ b/starting/index.md @@ -51,11 +51,11 @@ updated: 25 November 2019

    Next steps

    If you're new to open source, start with these essential steps:

      -
    1. Create a comprehensive README
      2. -
    2. Choose and add a license
      3. -
    3. Set up contribution guidelines
      4. -
    4. Add a code of conduct
      5. -
    5. Configure your repository
      6. +
    6. Create a comprehensive README
      7. +
    7. Choose and add a license
      8. +
    8. Set up contribution guidelines
      9. +
    9. Add a code of conduct
      10. +
    10. Configure your repository
diff --git a/starting/releasing.md b/starting/releasing.md new file mode 100644 index 0000000..b6f1baf --- /dev/null +++ b/starting/releasing.md @@ -0,0 +1,33 @@ +--- +page: starting-releasing +title: Releasing Code +nav: Starting +group: navigation +weight: 2 +layout: default +subnav: + - title: Naming + tag: naming + - title: Licensing + tag: licensing + - title: Client Permissions + tag: client-permissions + - title: Choosing Tools + tag: choosing-tools + - title: Accessibility + tag: accessibility + - title: Security + tag: security + - title: Release Process + tag: release-process + - title: Changelog + tag: changelog + - title: Team and Credit Management + tag: credit-management +updated: 17 September 2019 +--- + +
+ {% capture markup %}{% include markdown/Releasing.md %}{% endcapture %} + {{ markup | markdownify }} +
From 7fe49642c0ba1b2fd8280a5d487bdcea0a5d1a2a Mon Sep 17 00:00:00 2001 From: Jeffrey Paul Date: Wed, 17 Sep 2025 16:10:08 -0500 Subject: [PATCH 4/6] Add Choose Your Path landing page - Replace homepage with user-friendly landing page that guides visitors to relevant content - Create four distinct paths: - Starting Your First Project (primary path for beginners) - Maintaining an Existing Project (secondary path for active maintainers) - Growing and Sustaining (tertiary path for mature projects) - References and Resources (reference path for tools and standards) - Add visual styling with path cards, hover effects, and color-coded sections - Include call-to-action buttons for each section - Maintain mobile-responsive design - Preserve original homepage content as index-backup.md - Keep introduction content accessible at bottom of page This landing page makes the site more approachable for both beginners and seasoned maintainers by clearly directing them to relevant guidance. --- index-backup.md | 88 ++++++++++++++++ index.md | 267 ++++++++++++++++++++++++++++++++++++------------ 2 files changed, 288 insertions(+), 67 deletions(-) create mode 100644 index-backup.md diff --git a/index-backup.md b/index-backup.md new file mode 100644 index 0000000..3127d6f --- /dev/null +++ b/index-backup.md @@ -0,0 +1,88 @@ +--- +page: introduction +title: Introduction +nav: Home +group: navigation +weight: 1 +layout: default +subnav: + - title: Introduction + tag: intro + - title: Why OSS? + tag: why-oss + - title: OSS for Agencies + tag: agencies + - title: Open Source vs. Open Process + tag: process + - title: Contributing to this guide + tag: contributing +updated: 25 November 2019 +--- + +
+
+

Table of Contents

+
+ +
+

Home

+ +
+ +
+

Starting or Releasing a Project

+ +
+ +
+

Maintaining, Supporting, and Enhancing

+ +
+ +
+

Growing and Sustaining a Project

+ +
+ +
+

References and Resources

+ +
+
+ +
+ {% capture introduction %}{% include markdown/Introduction.md %}{% endcapture %} + {{ introduction | markdownify }} +
diff --git a/index.md b/index.md index 3127d6f..b3f21b0 100644 --- a/index.md +++ b/index.md @@ -1,88 +1,221 @@ --- page: introduction -title: Introduction +title: Open Source Best Practices +description: Guidance for every stage of your open source project. nav: Home group: navigation weight: 1 layout: default -subnav: - - title: Introduction - tag: intro - - title: Why OSS? - tag: why-oss - - title: OSS for Agencies - tag: agencies - - title: Open Source vs. Open Process - tag: process - - title: Contributing to this guide - tag: contributing updated: 25 November 2019 --- -
+
-

Table of Contents

+

Open Source Best Practices

+

Welcome! This guide helps you build and maintain healthy open source projects.
+ Choose the path that best fits where you are today:

-
-

Home

- -
+
+
+

🚀 Starting Your First Project

+

New to open source? Get your project off to a great start with these essentials:

+ +
+ Explore the full Starting or Releasing a Project section » +
+
-
-

Starting or Releasing a Project

- -
+
+

🔧 Maintaining an Existing Project

+

Already have a project? Keep it healthy and growing with these practices:

+ +
+ Explore the full Maintaining, Supporting, and Enhancing a Project section » +
+
+ +
+

📈 Growing and Sustaining

+

Looking beyond day-to-day maintenance? Scale your project and community:

+ +
+ Explore the full Growing and Sustaining a Project section » +
+
-
-

Maintaining, Supporting, and Enhancing

- -
- -
-

Growing and Sustaining a Project

- +
+

📚 References and Resources

+

Quick access to tools, standards, and examples:

+ +
+ See the full References and Resources section » +
+
-
-

References and Resources

- +
+

About This Guide

+

This guide is written with groups releasing smaller-scale open source software in mind. The majority of our open source projects are narrowly-focused extensions to existing ecosystems, such as WordPress plugins or front-end components, and this set of best practices reflects that.

+ +
+

New to open source? Learn why open source matters

+

Want to contribute to this guide? See our contributing guidelines

+
- {% capture introduction %}{% include markdown/Introduction.md %}{% endcapture %} - {{ introduction | markdownify }} + {% capture introduction %}{% include markdown/Introduction.md %}{% endcapture %} + {{ introduction | markdownify }}
+ + \ No newline at end of file From 2f8b6f1394707f65e7488bb6e9c11212f9310deb Mon Sep 17 00:00:00 2001 From: Jeffrey Paul Date: Wed, 17 Sep 2025 16:16:48 -0500 Subject: [PATCH 5/6] Add redirects for backward compatibility with new navigation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create url-redirect-mapping.csv documenting all old to new URL mappings - Configure jekyll-redirect-from plugin in _config.yml - Add redirect_from front matter to all moved pages: - /community/ → /starting/community/ - /releasing/ → /starting/releasing/ - /maintaining/ → /maintaining/maintaining/ - /github-process/ → /maintaining/github-process/ - /testing/ → /maintaining/testing/ - Add homepage redirects for old documentation URLs: - /docs/ → / (new landing page) - /docs/index.html → / (new landing page) - Preserve all existing links and bookmarks - Ensure seamless user experience during transition This maintains backward compatibility while users and search engines adapt to the new lifecycle-oriented navigation structure. --- _config.yml | 4 ++++ index.md | 3 +++ maintaining/github-process.md | 2 ++ maintaining/maintaining.md | 2 ++ maintaining/testing.md | 2 ++ starting/community.md | 2 ++ starting/releasing.md | 2 ++ url-redirect-mapping.csv | 37 +++++++++++++++++++++++++++++++++++ 8 files changed, 54 insertions(+) create mode 100644 url-redirect-mapping.csv diff --git a/_config.yml b/_config.yml index 627db7b..531ac4f 100644 --- a/_config.yml +++ b/_config.yml @@ -17,3 +17,7 @@ kramdown: input: GFM sass: sass_dir: _includes/_sass + +# Plugins +plugins: + - jekyll-redirect-from diff --git a/index.md b/index.md index b3f21b0..3ca2f08 100644 --- a/index.md +++ b/index.md @@ -6,6 +6,9 @@ nav: Home group: navigation weight: 1 layout: default +redirect_from: + - /docs/ + - /docs/index.html updated: 25 November 2019 --- diff --git a/maintaining/github-process.md b/maintaining/github-process.md index ef8c1a0..edba56c 100644 --- a/maintaining/github-process.md +++ b/maintaining/github-process.md @@ -5,6 +5,8 @@ nav: Maintaining group: navigation weight: 3 layout: default +redirect_from: + - /github-process/ subnav: - title: Issue and PR labels tag: issue-pr-labels diff --git a/maintaining/maintaining.md b/maintaining/maintaining.md index 2a95ed3..eb76289 100644 --- a/maintaining/maintaining.md +++ b/maintaining/maintaining.md @@ -5,6 +5,8 @@ nav: Maintaining group: navigation weight: 3 layout: default +redirect_from: + - /maintaining/ subnav: - title: Maintainers and Contributors tag: maintainers-contributors diff --git a/maintaining/testing.md b/maintaining/testing.md index a7d7c1a..8b3e259 100644 --- a/maintaining/testing.md +++ b/maintaining/testing.md @@ -5,6 +5,8 @@ nav: Maintaining group: navigation weight: 3 layout: default +redirect_from: + - /testing/ subnav: - title: Critical Flows and Test Cases tag: critical-flows diff --git a/starting/community.md b/starting/community.md index 4903125..7675308 100644 --- a/starting/community.md +++ b/starting/community.md @@ -5,6 +5,8 @@ nav: Starting group: navigation weight: 2 layout: default +redirect_from: + - /community/ subnav: - title: Readme tag: readme diff --git a/starting/releasing.md b/starting/releasing.md index b6f1baf..b91ae2a 100644 --- a/starting/releasing.md +++ b/starting/releasing.md @@ -5,6 +5,8 @@ nav: Starting group: navigation weight: 2 layout: default +redirect_from: + - /releasing/ subnav: - title: Naming tag: naming diff --git a/url-redirect-mapping.csv b/url-redirect-mapping.csv new file mode 100644 index 0000000..4609b13 --- /dev/null +++ b/url-redirect-mapping.csv @@ -0,0 +1,37 @@ +Old URL,New URL,Redirect Method,Notes +/community/,/starting/community/,redirect_from,Community page moved to starting section +/releasing/,/starting/releasing/,redirect_from,Releasing page moved to starting section +/maintaining/,/maintaining/maintaining/,redirect_from,Maintaining page moved to maintaining section +/github-process/,/maintaining/github-process/,redirect_from,GitHub Process page moved to maintaining section +/testing/,/maintaining/testing/,redirect_from,Testing page moved to maintaining section +/community/#readme,/starting/community/#readme,redirect_from,README section within community +/community/#contributing,/starting/community/#contributing,redirect_from,Contributing section within community +/community/#code-of-conduct,/starting/community/#code-of-conduct,redirect_from,Code of Conduct section within community +/releasing/#naming,/starting/releasing/#naming,redirect_from,Naming section within releasing +/releasing/#licensing,/starting/releasing/#licensing,redirect_from,Licensing section within releasing +/releasing/#client-permissions,/starting/releasing/#client-permissions,redirect_from,Client Permissions section within releasing +/releasing/#choosing-tools,/starting/releasing/#choosing-tools,redirect_from,Choosing Tools section within releasing +/releasing/#accessibility,/starting/releasing/#accessibility,redirect_from,Accessibility section within releasing +/releasing/#security,/starting/releasing/#security,redirect_from,Security section within releasing +/releasing/#release-process,/starting/releasing/#release-process,redirect_from,Release Process section within releasing +/releasing/#changelog,/starting/releasing/#changelog,redirect_from,Changelog section within releasing +/releasing/#credit-management,/starting/releasing/#credit-management,redirect_from,Credit Management section within releasing +/maintaining/#maintainers-contributors,/maintaining/maintaining/#maintainers-contributors,redirect_from,Maintainers section within maintaining +/maintaining/#issue-pr-mgmt,/maintaining/maintaining/#issue-pr-mgmt,redirect_from,Issue PR Management section within maintaining +/maintaining/#dotorg-support,/maintaining/maintaining/#dotorg-support,redirect_from,WordPress.org Support section within maintaining +/maintaining/#slack-channel-github-activity,/maintaining/maintaining/#slack-channel-github-activity,redirect_from,GitHub Activity section within maintaining +/maintaining/#dslack-channel-dotorg-activity,/maintaining/maintaining/#dslack-channel-dotorg-activity,redirect_from,WordPress.org Activity section within maintaining +/maintaining/#version-control,/maintaining/maintaining/#version-control,redirect_from,Version Control section within maintaining +/maintaining/#wp-php-mins,/maintaining/maintaining/#wp-php-mins,redirect_from,WordPress PHP Minimums section within maintaining +/github-process/#issue-pr-labels,/maintaining/github-process/#issue-pr-labels,redirect_from,Issue PR Labels section within github-process +/github-process/#milestones,/maintaining/github-process/#milestones,redirect_from,Milestones section within github-process +/github-process/#branching-merging-deploying,/maintaining/github-process/#branching-merging-deploying,redirect_from,Branching section within github-process +/github-process/#documentation,/maintaining/github-process/#documentation,redirect_from,Documentation section within github-process +/github-process/#support-levels,/maintaining/github-process/#support-levels,redirect_from,Support Levels section within github-process +/github-process/#opengraph-image,/maintaining/github-process/#opengraph-image,redirect_from,OpenGraph Image section within github-process +/github-process/#dependency-management,/maintaining/github-process/#dependency-management,redirect_from,Dependency Management section within github-process +/github-process/#coding-standards,/maintaining/github-process/#coding-standards,redirect_from,Coding Standards section within github-process +/github-process/#continuous-integration,/maintaining/github-process/#continuous-integration,redirect_from,Continuous Integration section within github-process +/testing/#critical-flows,/maintaining/testing/#critical-flows,redirect_from,Critical Flows section within testing +/testing/#code-coverage,/maintaining/testing/#code-coverage,redirect_from,Code Coverage section within testing +/testing/#e2e-testing,/maintaining/testing/#e2e-testing,redirect_from,E2E Testing section within testing From f6c7f7e2c174d5ce9c6dd3438d16b1e71d4c054c Mon Sep 17 00:00:00 2001 From: Jeffrey Paul Date: Wed, 17 Sep 2025 17:14:19 -0500 Subject: [PATCH 6/6] removed OSBP transition files, not needed for ongoing purposes --- content-migration-mapping.csv | 12 ----- index-backup.md | 88 -------------------------------- nav-outline.md | 96 ----------------------------------- stub-template.md | 76 --------------------------- 4 files changed, 272 deletions(-) delete mode 100644 content-migration-mapping.csv delete mode 100644 index-backup.md delete mode 100644 nav-outline.md delete mode 100644 stub-template.md diff --git a/content-migration-mapping.csv b/content-migration-mapping.csv deleted file mode 100644 index df749b9..0000000 --- a/content-migration-mapping.csv +++ /dev/null @@ -1,12 +0,0 @@ -Current Title,Current File Path,Proposed Section,New File Path,Notes -Introduction,index.md,Homepage,/index.md,Stays as homepage -Community,community.md,Starting,/starting/community.md,README, Code of Conduct, Contributing Guidelines -Releasing Code,releasing.md,Starting,/starting/releasing.md,Naming, Licensing, Client Permissions, Choosing Tools, Accessibility, Security, Release Process, Changelog, Team and Credit Management -Maintenance Process,maintaining.md,Maintaining,/maintaining/maintaining.md,Maintainers and Contributors, Issue and PR Management, WordPress.org Support, Tracking GitHub activity, Tracking WordPress.org activity, Version Control, WordPress and PHP Minimums -GitHub Process,github-process.md,Maintaining,/maintaining/github-process.md,Issue and PR labels, Milestones, Branching Merging and Deploying, Documentation, Support Levels, OpenGraph Image, Dependency Management, Coding Standards, Continuous Integration -Testing,testing.md,Maintaining,/maintaining/testing.md,Critical Flows and Test Cases, Code Coverage, E2E Testing -CODE_OF_CONDUCT.md,CODE_OF_CONDUCT.md,Repository Management,/,NOT MOVED - Repository management file -CONTRIBUTING.md,CONTRIBUTING.md,Repository Management,/,NOT MOVED - Repository management file -CREDITS.md,CREDITS.md,Repository Management,/,NOT MOVED - Repository management file -LICENSE.md,LICENSE.md,Repository Management,/,NOT MOVED - Repository management file -README.md,README.md,Repository Management,/,NOT MOVED - Repository management file diff --git a/index-backup.md b/index-backup.md deleted file mode 100644 index 3127d6f..0000000 --- a/index-backup.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -page: introduction -title: Introduction -nav: Home -group: navigation -weight: 1 -layout: default -subnav: - - title: Introduction - tag: intro - - title: Why OSS? - tag: why-oss - - title: OSS for Agencies - tag: agencies - - title: Open Source vs. Open Process - tag: process - - title: Contributing to this guide - tag: contributing -updated: 25 November 2019 ---- - -
-
-

Table of Contents

-
- -
-

Home

- -
- -
-

Starting or Releasing a Project

- -
- -
-

Maintaining, Supporting, and Enhancing

- -
- -
-

Growing and Sustaining a Project

- -
- -
-

References and Resources

- -
-
- -
- {% capture introduction %}{% include markdown/Introduction.md %}{% endcapture %} - {{ introduction | markdownify }} -
diff --git a/nav-outline.md b/nav-outline.md deleted file mode 100644 index 96f318a..0000000 --- a/nav-outline.md +++ /dev/null @@ -1,96 +0,0 @@ -# Proposed Navigation Structure - -This document outlines the proposed restructuring of the Open Source Best Practices site navigation to align with the project lifecycle. - -## A. Starting or Releasing a Project - -Content for first-time open source releasers and new project maintainers: - -- **README.md best practices** → Maps to: `community.md` (README section) -- **License file** → Maps to: `releasing.md` (Licensing section) -- **Contribution guidelines** → Maps to: `community.md` (Contributing Guidelines section) -- **Code of Conduct** → Maps to: `community.md` (Code of Conduct section) -- **Semantic Versioning & Release Tags** → Maps to: `releasing.md` (Changelog section) -- **Initial Repo Setup (branches, labels, templates)** → Maps to: `github-process.md` (Issue and PR labels, Branching sections) - -## B. Maintaining, Supporting, and Enhancing a Project - -Content for ongoing project maintenance and community management: - -- **CHANGELOG standards** → Maps to: `releasing.md` (Changelog section) -- **Issue triage & labeling** → Maps to: `github-process.md` (Issue and PR labels section) -- **Pull Request guidelines** → Maps to: `github-process.md` (Issue and PR labels section) -- **Continuous Integration / Testing** → Maps to: `github-process.md` (Continuous Integration section) + `testing.md` -- **Documentation standards** → Maps to: `github-process.md` (Documentation section) -- **Security handling** → Maps to: `releasing.md` (Security section) -- **Communication best practices** → Maps to: `maintaining.md` (Issue and PR Management section) - -## C. Growing and Sustaining a Project - -Content for mature projects and community growth: - -- **Governance models** → **MISSING** - Needs to be created -- **Community recognition** → Maps to: `releasing.md` (Team and Credit Management section) -- **Roadmaps & planning** → Maps to: `github-process.md` (Milestones section) -- **Sponsorships / funding** → **MISSING** - Needs to be created -- **Succession planning** → **MISSING** - Needs to be created -- **Sunsetting/archiving projects** → **MISSING** - Needs to be created - -## D. References and Resources - -Supporting materials and external resources: - -- **Recommended tools & services** → **MISSING** - Needs to be created -- **External standards (SPDX, OSI, SemVer)** → **MISSING** - Needs to be created -- **Example repositories** → **MISSING** - Needs to be created - -## Content Mapping Summary - -### Existing Content (Maps to new structure): -- `index.md` (Introduction) → Stays as homepage -- `releasing.md` → Maps to sections A and B -- `maintaining.md` → Maps to section B -- `community.md` → Maps to section A -- `github-process.md` → Maps to sections A and B -- `testing.md` → Maps to section B - -### Missing Content (Needs to be created): -- Governance models -- Sponsorships/funding -- Succession planning -- Sunsetting/archiving projects -- Recommended tools & services -- External standards -- Example repositories - -## Proposed URL Structure - -- `/starting/` - Landing page for new project guidance -- `/starting/readme/` - README best practices -- `/starting/license/` - License file guidance -- `/starting/contributing/` - Contribution guidelines -- `/starting/code-of-conduct/` - Code of Conduct -- `/starting/versioning/` - Semantic Versioning & Release Tags -- `/starting/repo-setup/` - Initial Repo Setup - -- `/maintaining/` - Landing page for ongoing maintenance -- `/maintaining/changelog/` - CHANGELOG standards -- `/maintaining/issues/` - Issue triage & labeling -- `/maintaining/pull-requests/` - Pull Request guidelines -- `/maintaining/ci-testing/` - Continuous Integration / Testing -- `/maintaining/documentation/` - Documentation standards -- `/maintaining/security/` - Security handling -- `/maintaining/communication/` - Communication best practices - -- `/growing/` - Landing page for project growth -- `/growing/governance/` - Governance models -- `/growing/community-recognition/` - Community recognition -- `/growing/roadmaps/` - Roadmaps & planning -- `/growing/sponsorships/` - Sponsorships / funding -- `/growing/succession/` - Succession planning -- `/growing/sunsetting/` - Sunsetting/archiving projects - -- `/references/` - Landing page for resources -- `/references/tools/` - Recommended tools & services -- `/references/standards/` - External standards -- `/references/examples/` - Example repositories diff --git a/stub-template.md b/stub-template.md deleted file mode 100644 index f0f4b01..0000000 --- a/stub-template.md +++ /dev/null @@ -1,76 +0,0 @@ -# Stub Page Template for Open Source Best Practices - -This template provides a consistent structure for section landing pages across the Open Source Best Practices site. - -## Template Structure - -```markdown ---- -page: [section-name] -title: [Section Title] -nav: [Navigation Title] -group: navigation -weight: [number] -layout: default -subnav: - - title: [First Child Page] - tag: [tag-name] - - title: [Second Child Page] - tag: [tag-name] - - title: [Third Child Page] - tag: [tag-name] -updated: [date] ---- - -
-
-

[Section Title]

-

[One-sentence summary for metadata and page description]

-
- -
-

Who this is for

-
    -
  • [Brief description of primary audience]
    • -
  • [Secondary audience if applicable]
    • -
  • [Tertiary audience if applicable]
    • -
-
- -
-

What you'll find here

-
    -
  • [High-level overview of first type of guide]
    • -
  • [High-level overview of second type of guide]
    • -
  • [High-level overview of third type of guide]
    • -
  • [High-level overview of fourth type of guide]
    • -
  • [High-level overview of fifth type of guide]
    • -
-
- -
-

Next steps

-

[Brief introduction to the next steps section]

-
    -
  1. [Link to first child page]
    2. -
  2. [Link to second child page]
    3. -
  3. [Link to third child page]
    4. -
-
-
-``` - -## Usage Guidelines - -1. **Replace bracketed placeholders** with actual content -2. **Keep descriptions concise** - aim for 1-2 sentences per bullet point -3. **Use plain language** - avoid jargon when possible -4. **Link to existing content** where available, or create placeholder links for future content -5. **Maintain consistent tone** - helpful, encouraging, and practical - -## Section-Specific Notes - -- **Starting**: Focus on first-time open source releasers -- **Maintaining**: Target active project maintainers -- **Growing**: Address mature project needs -- **References**: Provide quick access to tools and standards