Pattern idea: Common metadata format to aid discovery of Inner Source projects

[tsadler1988]

Following on from a conversation in the ISC Slack, would a metadata file added to Inner Source repos in source control (e.g. inner-source.json or inner-source.yaml) aid discovery of Inner Source repos within an organisation? If so, should we define a common format for this metadata?

Alternatively, should this information be derivable from your SCM tool (GitHub/GitLab/Bitbucket etc.)? This would negate the need to add a file to each inner source repo in your organisation.

One suggested format:

# description should be one paragraph
description: This is where you describe the purpose to your users.  
Is this a component library, is this a template project, what 
benefit is there to me if I use this library in my own project. You
Could even say something about how the project is versioned here. 


# github pages or a conflunce link by default 
# could be a readme for the project
documentation: https://github.com/InnerSourceCommons/InnerSourceLearningPath/

# technologies used
technologies: Javascript, React, Graphql, etc..

# comma separated list, name <email> (url)
maintainers: Barney Rubble <[email protected]> (http://barnyrubble.tumblr.com/)

Prior art:

• GrimoireLab projects file format.
• Related initiative at the Eclipse Foundation

[mrsanz]

I'd like to see innersource.yaml or innersource.json be the standard. readme.md follows the same convention of creating a new word ;)

[grey-nicholson-bbc]

More prior art: Description of a Project (DOAP); an example in the wild

[Ludmila-N]

I am inclined to follow existing standards where available; specifically, there's already a standard for the metadata file name in my org with some of the similar entries (i.e., technologies). Will think which specific entries make sense for InnerSource projects. As far as aiding discovery of the InnerSource projects, I'm inclined to use the presence of CONTRIBUTING.MD file in the code repository as the best indicator of host team readiness for contributions.

[arnom-ms]

I am not sure I am a fan of another data container. Would it not make sense to have the metadata describing the project/repo in the top part of the readme? Secondly, I am also not convinced tracking the maintainers in a file is a good idea as people in general are not particularly good in updating things like that. I would rather suggest to use the APIs of infrastructure (GitHub, GitLab.. etc) instead. Keeping authors in the individual file headers like it is done in open source projects is what should be done for InnerSource as well IMHO (should you care about that information within your company). Let's avoid introducing more concepts if there is already a concept that fits the scenario..

[dineshdh]

Not a huge fan of adding too many meta data files to a repo. Ideally all public repos in a company are Inner source projects, but this is not always the case. Inflight of that I think explicitly registering your project may be an idea. See https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/118

[spier]

For a similar purpose, SAP's reference implementation of the InnerSource Portal proposes an innersource.json file in the root of the repository with some extra attributes.

@Michadelic could you elaborate a bit out why you chose the given approach, and how it has been working out for you so far?

The approach with that metadata could indeed be an extension of the InnerSource Portal pattern, or even a new pattern on it's own.

[Michadelic]

Sure, instead of self-registering with a central service as described in #118 we use a decentralized approach with GitHub topics and local metadata checked into the project (similar to a package.json descriptor for nodejs projects). The crawler checks all repos with the topic and optionallly loads the innersource.json file with additional metadata about the project to enricht the display of the portal entry with further details like skills required or a more readable title.

The advantage with this approach is that the metadata is under full control of the repo owner and can be modified very easily. It is technology-agnostic and flexible as well, we can also add new fields on top if needed. Self-registering with a GitHub topic and creating the file does not take more that a couple of minutes. We do have a significant increase of projects registering since we have this simple but effective mechanism in place.

More infos about the metadata structure: https://github.com/SAP/project-portal-for-innersource/blob/main/CONTRIBUTING.md#listing-project-in-the-project-portal-for-innersource

[spier]

@tsadler1988 given the conversations in this issue, do you have a preferred path forward?

Options that I can think of right now:

1. Adding a bit more info about SAP's approach with the innersource.json file to the InnerSource Portal Pattern
2. Creating a new pattern just around relevant metadata (maybe describing what metadata is helpful for InnerSource collaboration and then listing the different available solutions, rather than prescribing a single solution?)

[spier]

Also FYI this is the latest syntax definition of SAP's innersource.json file.