Skip to content

Commit 191a488

Browse files
librementelibremente
authored
Independent versioning (#47)
* add: country extension versioning * feat: inserted in README info about versioning schema * fix: renamed schema.rst into schema.core.rst * feat: added badge for release * fix: badge in version numbering
1 parent 3391257 commit 191a488

File tree

7 files changed

+97
-31
lines changed

7 files changed

+97
-31
lines changed

‎README.md‎

Lines changed: 68 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,33 @@
11
# The `publiccode.yml` standard
22

3+
[![GitHub release](https://img.shields.io/github/release/italia/publiccode.yml.svg?style=plastic)](https://github.com/italia/publiccode.yml/releases)
34
[![Join the #publiccode channel](https://img.shields.io/badge/Slack%20channel-%23publiccode-blue.svg)](https://developersitalia.slack.com/messages/CAM3F785T)
45
[![Get invited](https://slack.developers.italia.it/badge.svg)](https://slack.developers.italia.it/)
6+
[![Docs
7+
Italia](https://docs.italia.it/media/static/projects/badges/passing.svg)](https://docs.italia.it/italia/developers-italia/publiccodeyml/it/master/index.html)
8+
[![Documentation](https://img.shields.io/badge/Documentation-Docs%20Italia-blue.svg)](https://docs.italia.it/italia/developers-italia/publiccodeyml/it/master/index.html)
59

6-
A metadata description standard for public software and policy repositories
7-
that is easy to use both for developers and people with less technical
8-
background, in order to make the software developed by Public Administrations
9-
and Public Organisations easily discoverable.
10+
> A metadata description standard for public software
1011
11-
**Latest release: [Version
12-
0.1](https://github.com/italia/publiccode.yml/releases/latest)**
12+
---
1313

14-
[See all versions](https://github.com/italia/publiccode.yml/releases)
14+
## Table of Contents
1515

16-
This project follows the Semantic Versioning. For more information see
17-
[SemVer.org](https://semver.org/).
16+
- [Description](#description)
17+
- [What is this file for](#what-this-file-is-for)
18+
- [Documentation](#documentation)
19+
- [Finding Projects](#finding-projects)
20+
- [Versioning](#versioning)
21+
- [Contributing](#contributing)
22+
- [Authors](#authors)
23+
- [License](#license)
1824

19-
Furthermore, the project uses branches and tags in the following way:
20-
* The `master` branch contains the latest stable version of the standard.
21-
* The `development` branch contains the improvements proposed for the next
22-
version.
23-
* GitHub's [release page](https://github.com/italia/publiccode.yml/releases)
24-
contains all the released versions of the standard. Releases are done
25-
following the tag version for consistency (e.g., tag v0.1 implies release
26-
v0.1).
25+
## Description
2726

28-
The PublicCode specification is developed by the [Italian Digital
29-
Transformation Team](https://teamdigitale.governo.it) and the
30-
[Authors](AUTHORS.md).
27+
A metadata description standard for public software and policy repositories
28+
that is easy to use both for developers and people with less technical
29+
background, in order to make the software developed by Public Administrations
30+
and Public Organisations easily discoverable.
3131

3232
## What this file is for
3333

@@ -55,6 +55,15 @@ The `publiccode.yml` file format should both be able to easily be added to any
5555
new project, as well as grow with the project as it expands beyond the original
5656
context it was developed in.
5757

58+
## Documentation
59+
60+
This repository is structured in order to be compatible with the [Docs Italia](https://docs.italia.it/italia/developers-italia/publiccodeyml/it/master/index.html)
61+
platform. As such, the content in the relevant folders will be
62+
compiled and rendered inside that platform. The `Docs Italia` platform is
63+
able to handle different releases and localised versions of the same file
64+
drawing from the document's GitHub repository. As such, the platform is to be
65+
considered the default landing page for the project.
66+
5867
## Finding projects
5968

6069
Finding projects depends on how the search API is structured for every hosting
@@ -68,16 +77,49 @@ The Italian Digital Transformation Team is also working on providing a scanner
6877
which looks for all publiccode files on all publicly accessible websites, and
6978
exposing them as open data.
7079

80+
## Versioning
81+
82+
**Latest release:** [![GitHub release](https://img.shields.io/github/release/italia/publiccode.yml.svg?style=plastic)](https://github.com/italia/publiccode.yml/releases) [See all versions](https://github.com/italia/publiccode.yml/releases)
83+
84+
This project follows the Semantic Versioning. For more information see
85+
[SemVer.org](https://semver.org/).
86+
87+
Furthermore, the project uses branches and tags in the following way:
88+
* The `master` branch contains the latest stable version of the standard.
89+
* The `development` branch contains the improvements proposed for the next
90+
version.
91+
* GitHub's [release page](https://github.com/italia/publiccode.yml/releases)
92+
contains all the released versions of the standard. Releases are done
93+
following the tag version for consistency.
94+
95+
However, since the repository contains both the core schema and the
96+
country-specific ones, it is necessary to further refine the versioning.
97+
As such, each update at the core and/or to a country-specific extension will be
98+
tagged as follows:
99+
100+
> core:x.y.z/<cc>:a.b.c
101+
102+
where <cc> is the country code defined using one of the ISO 3166-1 alpha-2
103+
codes.
104+
105+
This versioning schema is fundamental in this project since the
106+
`publiccode.yml` file contains references to the core release in the
107+
`publiccodeYmlVersion` key and each country-specific schema contains
108+
a `version` key.
109+
110+
Examples of this versioning schema may be:
111+
112+
> * core:0.2/it:0.4
113+
> * core:0.2/fr:1.1
114+
71115
## Contributing
72116

73117
Feel free to submit [Pull Requests and to file Issues](CONTRIBUTING.md).
74118

75-
This repository is structured in order to be compatible with the `Docs Italia`
76-
platform. As such, the markdown content in the relevant folders will be
77-
compiled and rendered on top of that platform. The `Docs Italia` platform is
78-
able to handle different releases and localised versions of the same file
79-
drawing from the document's GitHub repository. As such, the platform is to be
80-
considered the default landing page for the project.
119+
## Authors
120+
The `publiccode.yml` specification is developed by the [Italian Digital
121+
Transformation Team](https://teamdigitale.governo.it) and the
122+
[Authors](AUTHORS.md).
81123

82124
## Licence
83125

‎docs/en/example/publiccode.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,8 @@ dependsOn:
121121

122122
it:
123123

124+
countryExtensionVersion: 0.1
125+
124126
conforme:
125127
accessibile: yes
126128
interoperabile: yes

docs/en/schema.rst renamed to docs/en/schema.core.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _core:
2+
13
The Standard (core)
24
===================
35

‎docs/it/example/publiccode.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,8 @@ dependsOn:
121121

122122
it:
123123

124+
countryExtensionVersion: 0.1
125+
124126
conforme:
125127
accessibile: yes
126128
interoperabile: yes

‎docs/it/forks.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ Gli autori che vorrebbero pubblicare un fork come una variante
107107
- Rivisitare la sezione denominata ``maintenance`` per aggiornare lo
108108
stato di manutenzione della variante.
109109

110-
Inoltre, gli autore **DOVREBBERO** valutare di fare anche i seguenti
110+
Inoltre, gli autori **DOVREBBERO** valutare di apportare anche i seguenti
111111
cambiamenti:
112112

113113
- Aggiungere le funzionalità che differenziano le varianti alla chiave

docs/it/schema.rst renamed to docs/it/schema.core.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _core:
2+
13
Lo standard (core)
24
==================
35

@@ -112,8 +114,8 @@ essere interpretata dal parser ma solamente visualizzata; i parser non
112114
devono assumere l’utilizzo del semantic versioning o altri specifici
113115
formati di versionamento.
114116

115-
Questa chiave può essere omessa nel caso in cui il software sia in un
116-
Paese iniziale di sviluppo e non sia stato ancora rilasciato.
117+
Questa chiave può essere omessa nel caso in cui il software sia in una fase
118+
iniziale di sviluppo e non sia stato ancora rilasciato.
117119

118120
Chiave ``releaseDate``
119121
~~~~~~~~~~~~~~~~~~~~~~

‎docs/it/schema.it.rst‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,24 @@ Italia
44
------
55

66
Tutte le estensioni elencate qui di seguito sono specifiche per l'Italia e, di
7-
conseguenza, devono essere inserite in una sezione denominata con
8-
il codice ``it``.
7+
conseguenza, devono essere inserite in una sezione denominata con il codice
8+
``it``. Tutti i Paesi sono specificati usando *country code* a due lettere
9+
seguendo lo standard ISO 3166-1 alpha-2.
10+
11+
12+
Chiave ``countryExtensionVersion``
13+
~~~~~~~~~~~~~~~~~~
14+
- Tipo: stringa
15+
- Presenza: obbligatoria
16+
- Esempio: ``"1.0"``
17+
18+
Questa chiave specifica la versione alla quale il presente schema di estensioni
19+
aderisce.
20+
21+
**Nota Bene:** il valore di questa chiave è indipendente da quello contenuto nella
22+
chiave top-level ``publiccodeYmlVersion`` (vedi :ref:`core`). In questo modo,
23+
il versioning di ogni schema di estensioni è indipendente sia dalla versione
24+
core dello schema che da ogni altra estensione per Paese.
925

1026
Sezione ``conforme``
1127
~~~~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)