phpDocumentor / phpDocumentor/guides
Decide on a stable xsi:schemaLocation URI for guides.xml
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 36
- Forks
- 22
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 24
Description
Follow-up from #827.
Our example guides.xml configs use xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd" -- a path relative to the monorepo's own vendor/ layout, which doesn't resolve for a consumer project. #827 proposed pointing it at a raw.githubusercontent.com URL instead, which sparked a discussion (@linawolf, @jaapio, @garvinhicking, @kaystrobach) that never reached a conclusion:
- A GitHub raw URL isn't versioned against the package version, so a project on an older phpdocumentor/guides-cli could validate against a newer/different XSD than the one it actually uses.
- The XSD doesn't change on every release (multiple package versions can share the same XSD), so per-release URIs would be more churn than the schema itself warrants.
- Ideas floated: version the XSD by major only (with the schema itself versioned, "version 3.0" as already declared in its
xsd:schemaroot), publish a "latest" alias, or host the XSD on our own domain (e.g. as part of the rendered docs site) rather than relying on GitHub raw content.
Needs an actual decision on where the XSD is published and how (if at all) it's versioned, then the example configs across the docs should be updated to match.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing #827 and the unresolved discussion about the example guides.xml configs and vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd. Decide where the XSD is published and how it is versioned, then update the example configs across the docs; the work is done when they use the agreed stable URI.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100