Skip to content

Latest commit

 

History

History
226 lines (164 loc) · 7.28 KB

README.md

File metadata and controls

226 lines (164 loc) · 7.28 KB

The publiccode.yml Standard

A metadata standard to describe software made by or for public administrations, making it discoverable and understandable for both developers and non-technical users.

What is publiccode.yml

Public administrations often create valuable software. Other administrations rarely reuse it, because the software is hard to find. It is also hard to tell whether a project fits another administration's context.

publiccode.yml is a human-readable and machine-readable metadata file placed in the root of a repository. It answers these questions:

  • What does this project do? (name, description, languages)
  • What is its status? (concept, development, beta, stable, obsolete)
  • Who maintains it and until when?
  • Who to contact for technical/support inquiries?
  • What legal frameworks is it designed for?
  • What are its dependencies?

It is designed to be easy to add to any new project and to grow as the project evolves.

Example

A minimal publiccode.yml file:

publiccodeYmlVersion: "1"
name: My text editor
url: "https://example.com/mysoftware/text-editor.git"
platforms:
  - windows
developmentStatus: development
softwareType: standalone/desktop
description:
  en:
    shortDescription: A lightweight text editor
    longDescription: >
          A lightweight yet powerful text editor designed for everyday use by developers,
          writers and public administrations. It also supports syntax highlighting.
    features:
       - Syntax highlighting
       - Collaborative editing features
       - Scripting interface
legal:
  license: AGPL-3.0-or-later
maintenance:
  type: community
  contacts:
    - name: Margaret Hamilton
localisation:
  localisationReady: true
  availableLanguages:
    - en
    - de
    - fr

See all available fields...

Adding publiccode.yml to a project

  1. Create a publiccode.yml file in the root directory of the repository, starting from the example above.
  2. Check it with the GitHub Action or the GitLab CI job, so that every change to the file is validated.
  3. Update the file when the project changes, for example its development status, maintainers or supported languages.

Finding projects

Each code hosting platform has its own search. On GitHub, this search finds every publiccode.yml file in the root directory of a repository:

Versioning

This project follows the Semantic Versioning.

See all versions

Contributing

Read the contributing guide before opening an issue or a pull request. Questions and proposals are welcome in Discussions.

Translations of the documentation live in publiccodeyml/translations.

The Standard's website is built using the Python Sphinx package and deployed on GitHub Pages from the publiccodeyml.github.io repository.

Prerequisites

Local development process

Each major version of the Standard has its own directory, spec/v0 and spec/v1. sphinx-build compiles one of them to static HTML files. Run this command to generate the version 1 website:

uv run sphinx-build spec/v1 build -c .

Then open a file of the build directory in a browser, for example build/index.html. Use spec/v0 instead for version 0.

Hot reloading

sphinx-autobuild rebuilds the website and reloads the browser on every change:

uv run sphinx-autobuild spec/v1 build -c .

All the versions

The published website puts every major version of the Standard side by side, one directory per major version (/v0/, /v1/, ...) with a version switcher on each page. A major version with a release is built from its newest release tag (v0.8.0, ...). A major version with no release yet is built from the spec/vN directory of the last commit of the current checkout, as a draft (1.0-rc, ...) marked by a banner. Every version uses the conf.py and templates of the current checkout, see poly.py. Tags come with the clone, then:

uv run sphinx-polyversion poly.py build/html

To preview the draft with the switcher, uncommitted changes included, without building the release tags:

uv run sphinx-polyversion poly.py build/html -l

Tooling

Tools and libraries that implement and support the publiccode.yml Standard.

Core tools

Core tools are developed alongside the publiccode.yml specification and provide its reference implementations and supporting components.

Core tools and how they interact: code repositories, publiccode-crawler, libpubliccode, Open Catalog API and catalog consumers

  • libpubliccode

    Parser and validator library. Reference implementation of the specification.

  • publiccode-crawler

    Crawler to discover and collect descriptor files for catalogs.

  • open-catalog-api

    RESTful API powering software catalogs for public administrations, used to store, query and expose all catalog data about FLOSS solutions.

  • publiccode-issueopener

    Opens GitHub issues to repos in a software catalog with invalid publiccode.yml files.

  • JSON Schema on SchemaStore

    JSON Schema definition mainly used by editors and IDEs for coarse validation and autocompletion.

Third-party tooling

Maintained separately from the core tooling, but widely used in practice.

  • publiccode-editor

    User friendly editor and basic validator for publiccode.yml files (maintained by Developers Italia, Italian Government).

License

Licensed under the CC0-1.0.