---

OSPO Alliance - FAQ project

:license: CC BY 4.0 International :project-url: (https://github.com/fredaatz/OSPO-FAQ)

OSPO FAQ is an open source project dedicated to providing modular, field based, curated and generic Frequently Asked Question corpus to be used, adapted, personnalized by Open Source Program Office teams or any similar unformal role dedicated to driving open source strategy in an organization.

---

Vision

Empower individuals, teams, and organizations in their open source strategy and governance, by providing a rich corpus of re-usable questions / answers, thus minimizing the time spent in providing support within their organization and enable any automation type of approach (intranet, bot, ..) to make OSPOs type roles more efficient and able to concentrate on business value priorities while proving a high quality support of their teams. Shared experience should also allow teams to find ready to use answers for new topics based on retex from others.

Therefor we intend to foster an Open Source FAQ as a Modular Documentation Framework: A collaborative, Git-native FAQ for open source governance topics. Each entry is a standalone Markdown file with structured metadata, making the FAQ easy to search, filter, translate, and maintain at scale.

Philosophy

Key aspects of the OSPO FAQ project:

• Resusable and modular questions & answers: Each topic / question is a standalone file / entry, easy to reuse and adapt.

• One file = one question. Atomic entries make PRs reviewable and git blame meaningful.

• Metadata first. Every entry carries a YAML front matter block that drives filtering, cross-referencing, and CI validation.

• All maturity level content: Purpose of the corpus is to cover basic to advanced questions both kick starting the FAQ approach as well as sharing more advanced or tricky questions.

• Question & answers as Code: All material is written in AsciiDoc for version-controlled, easily maintainable content. It also allows community based conversation to get to a shared, consensus based type of answer.

• Tags / category: TBC

• Inner/Open Source: OSPO FAQ will address the full scope of Inner Source and Open Source.-

• Controlled vocabulary. Tags, categories and statuses are defined up front in tags.yml — no freeform tagging.

• Git as the collaboration layer. Issues, PRs, labels and CI replace wikis and shared docs.

Available material

---

Repository structure

opensource-faq/
├── README.md                  ← you are here
├── CONTRIBUTING.md            ← contribution guide
├── tags.yml                   ← controlled tag registry
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── new-question.yml
│   │   └── correction.yml
│   ├── PULL_REQUEST_TEMPLATE.md
│   ├── labels.yml
│   └── workflows/
│       └── validate.yml       ← CI: lint + broken links + schema
├── _templates/
│   └── entry.md               ← copy this to create a new entry
└── faq/
    ├── licences/
    ├── contribution/
    ├── governance/
    ├── security/
    └── tooling/

---

Metadata schema (YAML front matter)

Every entry begins with a front matter block validated by CI. See _templates/entry.md for a ready-to-copy skeleton.

Field	Type	Required	Description
id	string	✅	Unique slug, kebab-case (e.g. gpl-vs-mit)
title	string	✅	The question, written as a full sentence
category	enum	✅	One of the top-level faq/ folders
tags	list	✅	From the controlled vocabulary in tags.yml
level	enum	✅	beginner, intermediate, or advanced
status	enum	✅	draft, reviewed, or outdated
last_updated	YYYY-MM	✅	Month of last meaningful edit
related	list	—	Slugs of related entries
sources	list	—	Canonical URLs supporting the answer

---

Categories

Folder	Scope
licences/	SPDX identifiers, compatibility, copyleft, permissive
contribution/	CLA, DCO, code review, commit conventions
governance/	Project leadership, RFCs, decision-making models
security/	Vulnerability disclosure, CVEs, supply-chain
tooling/	Git workflows, CI/CD, release automation

---

Git workflow

Creating a new entry

1. Open an issue using the New question template.
2. Fork the repo and copy _templates/entry.md to the right category folder.
3. Name the file after the id field: faq/licences/gpl-vs-mit.md.
4. Fill in front matter and content.
5. Open a PR — one entry per PR.

Fixing or updating an entry

1. Open an issue using the Correction template, or reference an existing one.
2. Edit the file, bump last_updated, and set status: reviewed if the change is substantive.
3. Open a PR referencing the issue.

Labels

Label	Meaning
new-question	PR adds a new FAQ entry
correction	PR fixes or updates an existing entry
needs-review	Awaiting expert validation
outdated	Entry flagged as stale
good-first-issue	Suitable for first-time contributors
duplicate	Covered by another entry

---

CI checks

Every PR triggers .github/workflows/validate.yml, which runs:

• YAML front matter validation — schema checked against _templates/entry.md spec.
• Broken link detection — via markdown-link-check.
• Duplicate ID detection — no two entries may share the same id.
• Tag registry check — all tags must exist in tags.yml.

---

Contributing

See CONTRIBUTING.md for the full guide.

---

License

This work is licensed under the Creative Commons Attribution 4.0 International License.
See the link:LICENSE[LICENSE] file for full details.