Clarify relation to Italian publiccode.yml

[rklec]

Maybe clarify the relation to https://github.com/italia/publiccode.yml-docs?

The Italian version seems to not be updated for 4 years, so is this outdated? Maybe then explicitly state that this version is based on the Italian standard?
Also possibly clarify, what the differences are?

The problem is https://editor.opencode.de/ generates v0.2 (see #256) and links to https://github.com/italia/publiccode.yml-docs in the YAML comments. This is very confusing for new users and one just needs to figure out what is happening here...

---

Also posted in the other repo: italia/publiccode.yml-docs#2

[libremente]

Hi @rklec, thanks for raising this!

I will try to clarify.
In 2022, Italy adopted publiccode.yml for its official national reuse model. As such, several tools have been developed in the Italian context (by Team Digitale / Digital Transformation Department) to increase the adoption, see the Editor and the catalogue for example.
As other European countries began adopting the standard, we migrated the project to this agnostic organization to serve as the international "source of truth."

Regarding the DE Editor, it appears to be a fork of the Italian editor, which is likely why it still contains links to the Italian documentation.

To summarize:

• This repository contains the most up-to-date version of the standard.
• The maintainers of the DE Editor tool should be notified to point their links toward this repo. Unfortunately I cannot find the repo in opencode's gitlab so I dunno who to contact but I will dig deeper.
• I agree we need to make this distinction clearer in our documentation to avoid future confusion.

I hope this helps!

[rklec]

Thanks but yeah this should be included in the Readme or so in a short version, so one does not need to search through the issues here?

[bfabio]

@rklec adding a bit more context here.

That repo is managed by Dipartimento per la Trasformazione Digitale (DTD) which is the Italian government body responsible for digital transformation in the public administration, but neither @libremente nor I are part of DTD anymore.

It's were the spec used to be, but now that we moved it to this organization it's now supposed to hold the just Italian translation, as the description says:

Italian translation of the publiccode.yml Standard
docs.italia.it/italia/developers-italia/publiccodeyml

In Italy there is an official docs platform called Docs Italia, which is basically a ReadTheDocs-based setup used by the public administration, and that's where the Italian translation is published.

Since this repository is now the SSOT for the spec and also contains translations of it (best-effort and informative only), what was done to avoid duplication was to link the Italian translation from this repo into the Italian docs via a git submodule, instead of maintaining a separate copy. So there is no "Italian fork" of the spec here.

At this point, if the Italian translation on Docs Italia is behind, the concrete action on the DTD side is simply to update the submodule pointer to the latest commit (and contribute back in case there are mismatches or missing bits in the Italian translation compared to the current spec).

That should hopefully explain what is going on without having to dig through old issues.

[fvsamson]

That repo is [...] the spec used to be, but now that we moved it to this organization it's now supposed to hold the just Italian translation, as the description says:

No, sorry that repository's description does not state that at all, please see yourself: https://github.com/italia/publiccode.yml-docs?tab=readme-ov-file#the-publiccodeyml-standard

This fact does cause major confusion at many, many places: Most publiccode.yml templates reference version 0.2, because that is obviously the newest version at principal repository for the publiccode.yml specification (i.e. the one we are discussing here, i.e. not this one we are discussing this issue in), because these templates logically reference only that repository.

It is neither useful or helpful to deny this major issue which has been persisting for 5 years (... and counting).

[rklec]

done to avoid duplication was to link the Italian translation from this repo into the Italian docs via a git submodule, instead of maintaining a separate copy.

Ah you likely mean italia/publiccode.yml-docs@d433a52 that links shows the actual git submodule (the commit that was adding this).

@fvsamson the description referenced by @bfabio is written in the GitHub description:

I personally agree though this is still very confusing as that little thing is unlikely to be read/easily overread. The Italian translation also just still seems to be quite outdated, after all.

An alternative solution would be to just archive the Italian translation and thus now maintain it here (adding a link to here).

[bfabio]

@rklec exactly, glad we now reached the same level of understanding, so to sum it up:

• OpenCode's editor should be updated, or maybe just dropped in favor of the upstream one maintained by the Italian DTD. There's no need to fork it just for the custom theme (they might have added different features though, I don't actually know if that's the case)
• https://github.com/italia/publiccode.yml-docs 's maintainers should fast-forward the submodule link to the latest translation in this repo, so the Italian translation on Docs Italia is up to date
• https://github.com/italia/publiccode.yml-docs 's maintainers should change their README, simply stating that's the translation repo that get published on Docs Italia

@rklec @fvsamson care to open those issues? 🙏