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/growing/index.md b/growing/index.md new file mode 100644 index 0000000..8f0e023 --- /dev/null +++ b/growing/index.md @@ -0,0 +1,66 @@ +--- +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 this is for

+ +
+ +
+

What you'll find here

+ +
+ +
+

Next steps

+

Key areas for project growth and sustainability:

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

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..3ca2f08 100644 --- a/index.md +++ b/index.md @@ -1,103 +1,224 @@ --- 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 +redirect_from: + - /docs/ + - /docs/index.html 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:

- +
+
+

๐Ÿš€ Starting Your First Project

+

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

+ + +
- +
+

๐Ÿ”ง Maintaining an Existing Project

+

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

+ + +
- - - +
+

๐Ÿ“ˆ Growing and Sustaining

+

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

+ + +
- -
-

Testing

- +
+

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.

+ +
- {% capture introduction %}{% include markdown/Introduction.md %}{% endcapture %} - {{ introduction | markdownify }} + {% capture introduction %}{% include markdown/Introduction.md %}{% endcapture %} + {{ introduction | markdownify }}
+ + \ No newline at end of file diff --git a/maintaining/github-process.md b/maintaining/github-process.md new file mode 100644 index 0000000..edba56c --- /dev/null +++ b/maintaining/github-process.md @@ -0,0 +1,35 @@ +--- +page: maintaining-github-process +title: GitHub Process +nav: Maintaining +group: navigation +weight: 3 +layout: default +redirect_from: + - /github-process/ +subnav: + - title: Issue and PR labels + tag: issue-pr-labels + - title: Milestones + tag: milestones + - title: Branching, Merging, and Deploying + tag: branching-merging-deploying + - title: Documentation + tag: documentation + - title: Support Levels + tag: support-levels + - title: OpenGraph Image + tag: opengraph-image + - title: Dependency Management + tag: dependency-management + - title: Coding Standards + tag: coding-standards + - title: Continuous Integration + tag: continuous-integration +updated: 17 September 2019 +--- + +
+ {% capture vcs %}{% include markdown/GitHub-Process.md %}{% endcapture %} + {{ vcs | markdownify }} +
diff --git a/maintaining/index.md b/maintaining/index.md new file mode 100644 index 0000000..0a06761 --- /dev/null +++ b/maintaining/index.md @@ -0,0 +1,63 @@ +--- +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 this is for

+
    +
  • Maintainers of active projects who want to improve quality
  • +
  • Teams supporting existing open source projects
  • +
  • Contributors looking to streamline contributions and set expectations
  • +
+
+ +
+

What you'll find here

+
    +
  • How to manage issues and pull requests
  • +
  • Setting up CI/testing workflows
  • +
  • Writing changelogs and documentation
  • +
  • Handling security and support
  • +
  • Community communication best practices
  • +
+
+ + +
diff --git a/maintaining/maintaining.md b/maintaining/maintaining.md new file mode 100644 index 0000000..eb76289 --- /dev/null +++ b/maintaining/maintaining.md @@ -0,0 +1,31 @@ +--- +page: maintaining-maintaining +title: Maintenance Process +nav: Maintaining +group: navigation +weight: 3 +layout: default +redirect_from: + - /maintaining/ +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..8b3e259 --- /dev/null +++ b/maintaining/testing.md @@ -0,0 +1,23 @@ +--- +page: maintaining-testing +title: Testing +nav: Maintaining +group: navigation +weight: 3 +layout: default +redirect_from: + - /testing/ +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/references/index.md b/references/index.md new file mode 100644 index 0000000..0cfda8e --- /dev/null +++ b/references/index.md @@ -0,0 +1,57 @@ +--- +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 this is for

+
    +
  • 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 here

+
    +
  • Recommended tooling (CI providers, automation bots)
  • +
  • Industry standards (SPDX, OSI, SemVer)
  • +
  • Example repositories with strong practices
  • +
  • Links to authoritative resources and documentation
  • +
+
+ +
+

Next steps

+

Essential resources for open source projects:

+
    +
  1. Tools & Services - Recommended tooling
  2. +
  3. Standards - SPDX, OSI, SemVer compliance
  4. +
  5. Examples - Best practice repositories
  6. +
+
+ +
+

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/community.md b/starting/community.md new file mode 100644 index 0000000..7675308 --- /dev/null +++ b/starting/community.md @@ -0,0 +1,23 @@ +--- +page: starting-community +title: Community +nav: Starting +group: navigation +weight: 2 +layout: default +redirect_from: + - /community/ +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 new file mode 100644 index 0000000..555ad29 --- /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 this is for

+
    +
  • 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 find here

+
    +
  • 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
  • +
+
+ +
+

Next steps

+

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

+
    +
  1. Create a comprehensive README
  2. +
  3. Choose and add a license
  4. +
  5. Set up contribution guidelines
  6. +
  7. Add a code of conduct
  8. +
  9. Configure your repository
  10. +
+
+
diff --git a/starting/releasing.md b/starting/releasing.md new file mode 100644 index 0000000..b91ae2a --- /dev/null +++ b/starting/releasing.md @@ -0,0 +1,35 @@ +--- +page: starting-releasing +title: Releasing Code +nav: Starting +group: navigation +weight: 2 +layout: default +redirect_from: + - /releasing/ +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 }} +
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