From cb432700d6dc58e84b84912929df9c10d14c6955 Mon Sep 17 00:00:00 2001 From: Fabio Bonelli Date: Mon, 18 Aug 2025 09:03:12 +0200 Subject: [PATCH] doc: update README.md Improve the README a little bit and add an example --- README.md | 94 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 60 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 144b1bf0..8812af56 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,8 @@
- A metadata description standard for public software that is easy to use both for - developers and people with less technical background in order to make the - software developed by Public Administrations and Public Organisations easily discoverable. + A metadata standard to describe software made by or for Public administrations, making it discoverable + and understandable for both developers and non-technical users.
@@ -27,6 +26,8 @@

+ Website + | Charter | @@ -36,31 +37,62 @@

-## What `publiccode.yml` is for - -Many great software projects are developed by public administrations, however -reuse of these projects is very limited. Some of the reasons for low uptake of -such projects is a lack of discoverability and that it is hard to find out what -project can actually work in the context of a different public administration. - -The `publiccode.yml` file is meant to solve all those problems. It is -an easily readable file for civil servants that are trying to figure out -whether a project will work for them, and easily readable by computers as -well. It contains information such as: -* the title and description of the project in English and/or other - languages; -* the development status, e.g. `concept`, `development`, `beta`, `stable`, - `obsolete`; -* which organisation developed the project; -* who is caring for the maintenance and when this expires; -* who to contact for technical or support inquiries; -* what national and local legal frameworks the project is designed - for; -* what software dependencies the project has. - -The `publiccode.yml` file format should both be able to easily be added to any -new project, as well as grow with the project as it expands beyond the original -context it was developed in. +## What is `publiccode.yml` + +Public Administrations often create valuable software, but reuse is often limited due to +poor discoverability or difficulty understanding if a project fits another administration's context. + +`publiccode.yml` solves this by providing a **human-readable and machine-readable metadata file**. + +It answers the 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: + +```yaml +publiccodeYmlVersion: "0" +name: My text editor +url: "https://example.com/mysoftware/text-editor.git" +platforms: + - windows +categories: + - office +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...**](https://yml.publiccode.tools/) ## Finding projects @@ -77,12 +109,6 @@ searching using the frontend or the API. This project follows the Semantic Versioning. For more information see [SemVer.org](https://semver.org/). -Furthermore, the project uses branches and tags in the following way: -* The `main` branch contains the improvements coming up in the next version. -* [Release page](https://github.com/publiccodeyml/publiccode.yml/releases) - contains all the released versions of the standard. Releases are tagged - with the Standard's version. - ## Contributing Feel free to submit [Pull Requests and to file Issues](CONTRIBUTING.md).