Consider creating a microservices key

[libremente]

Current situation

We are experiencing some issues with projects containing different repos inside.
Let's make an example.

PROJECT A
--> microservice 1
--> microservice 2
...
--> microservice n

Right now our solution is to tell PAs to create a new repo, let's call it metarepo, in order to store the information regarding the whole project. This metarepo will contain the publiccode.yml file which will be indexed in the catalog.
However, this solution has some flaws:
a) if the metarepo does not have a clear README file, the information regarding the other repositories (containing the n microservices) will be rather vague or lost. This is suboptimal.
b) the vitality index is calculated exclusively based upon the information regarding the metarepo and this does not make sense.

Proposal

We should add a key, called for example components or microservices, containing the list of repositories "related" to the project. As such, the metarepo will still contain the publiccode.yml file inside but each repo will be somehow listed in the catalog. This could also facilitate the calculation of the vitality index.

[bvhme]

Great proposal, I would like to say that the components seperately are 'codebases' or 'products' in their own right, so them having a `publiccode.yml` in the file seems right to me. Perhaps we can tell people that the metarepo, and especially the `README` in that can serve as an important entrypoint for the project and give them a reason to work on that. This readme could include things such as high level overview, the business cases etcetera.

…

On Tue, 18 Jun 2019 at 11:03, libremente ***@***.***> wrote: Current situation We are experiencing some issues with projects containing different repos inside. Let's make an example. PROJECT A --> microservice 1 --> microservice 2 ... --> microservice n Right now we are encouraging PAs to create a new repo, let's call it metarepo, in order to store the information regarding the whole project. This metarepo will contain the publiccode.yml file which will be indexed in the catalog. However, this solution has some flaws: a) if the metarepo does not have a clear README file, the information regarding the other repositories (containing the n microservices) will be rather vague or lost. This is suboptimal. b) the vitality index is calculated exclusively based upon the information regarding the metarepo and this does not make sense. Proposal We should add a key, called for example components or microservices containing the list of repositories "related" to the project. As such, the metarepo will still contain the publiccode.yml file inside but each repo will be somehow listed in the catalog. This could also facilitate the calculation of the vitality index. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <https://github.com/italia/publiccode.yml/issues/62?email_source=notifications&email_token=AAOUFPNRWKND36QCXNMNXWDP3CQGHA5CNFSM4HY523N2YY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4G2CSOUQ>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAOUFPJGAGLK2JW4WBIYNZLP3CQGHANCNFSM4HY523NQ> .

[libremente]

the components seperately are 'codebases' or 'products' in their own righ

@bvhme I understand your point of view and I believe this is true for well built standalone microservices or components which can be deployed "independently" from the other pieces. However, we are facing some products which have several not really independent pieces so I fear that inserting a publiccode.yml in each of those repo would generate confusion when browsing the catalog. I don't have a clear solution to this yet.

This readme could include things such as high level overview, the business cases etcetera.

Exactly, this is our view of a metarepo.

[Smart-City-Muenster]

Hi there from the city administration of Münster, Germany, and thanks for publiccode.yml!

We are starting to use the publiccode.yml for two current projects (and all other future projects, too, of course) and are facing this exact problem.
One project has a frontend and a backend in two repositories. They are not to be used indepently, though.
It's similar with a different project that splits up to three repositories: source code, documentation to rebuild hardware and design files.

What to do with these project structures? One publiccode.yml per project in the "main" repo (whatever this is)? The same publiccode.yml in every repo?

(Referencing the corresponding issues: bCyberGmbH/leezenflow-doku#2 , bCyberGmbH/leezenflow-design#1 , reedu-reengineering-education/smart-city-dashboard-backend#4 )

[bzg]

Hi all, this is also an issue I expect we will be facing with many source code from the French public sector.

I am in favor of the metarepo approach.

I'm tempted to use dependsOn to list the repositories that contribute to the metarepo, but I'm not sure entries in dependsOn can have a URL - if not, that's certainly a problem. (Also, this suggestion relies on my understanding of dependsOn as something different than the list of libraries one can find in e.g. package.json. I don't think adding the list of dependencies on publiccode.yml is a good idea. But this example suggests that my interpretation is okay.)

Another (complementary?) suggestion is to add a key to declare that a publiccode.yml belongs to a metarepo. Something like publiccodeYmlType: "meta" - but that name is not good enough IMHO.

I would refrain from adding a microservices key, as systems may have various architectures, this would lead to create more keys. If dependsOn cannot be used to declare contributing repos, I'd use something neutral like "components" - or anything that cannot be confused with dependencies/libraries/packages/etc.

[ruphy]

@Smart-City-Muenster it's a pleasure to have you here! I'm happy you're finding publiccode.yml useful!

I agree with your concerns and I also see what @bzg is saying. I think that having a components could indeed be a useful key. So far we've decided to either promote a repository as "main" repository, or simply create a new lightweight one which refers to the various components (see as an example https://github.com/italia-software/gitlab).

I agree that a machine-readable solution would be preferrable, and I love the name components for it! Would you like to open a Pull Request adding the key to the spec? We can then work on refining the details of it and get it approved

[Smart-City-Muenster]

Would you like to open a Pull Request adding the key to the spec?

Yes! Due to private reasons (good ones!) my PR is a bit late, sorry for that.