InnerSourcePatterns feat: promote discover-your-innersource

This pattern has been around in a draft/initial stage for a long time (almost 8 hears)!

As we believe that it does add some interest points, we want to try to improve it so that we feel comfortable publishing it in our pattern book.

Checklist

from the Contributor Handbook:

[x] Is validated by at least 1 (one) known instance
[ ] Uses the format described in the Pattern Template - validated in parts by Check: Pattern Syntax Validation
[ ] Follows the Pattern Style Guide
[ ] The title of the pattern is memorable, concise, and descriptive of what the pattern is about. For further tips see Naming Patterns.
[ ] The pattern links to related patterns of this level or higher.
[ ] Links from the pattern to outside resources are working and are referencing a trusted resource - whether links are working is verified by Check: Links
[ ] The pattern is added to at least one phase of the InnerSource Program Mind Map.
[ ] Spelling & Styles checks pass - see Check: Spelling & Styles

Extras

TBD

History

PR in which this pattern was originally created (almost 8 years ago!!!) - https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/60

Feb 28 '25 15:02 jeffabailey

Btw @jeffabailey if you want to use this pattern as a way to learn what it takes to get a pattern ready for publication in the book, by all means, keep pushing :) Just it might not be the easiest path on this particular pattern, as the current content of the pattern leaves a lot of room for improvement.

Mar 04 '25 22:03 spier

I pushed some changes to align the pattern with our pattern template.

Awesome, thank you!

If the ambition is to get this pattern live in our book, then we will have to invest quite some work here and keep the PR open for a while.

This, TBH! :)

Just it might not be the easiest path on this particular pattern, as the current content of the pattern leaves a lot of room for improvement.

Sounds like a great challenge and learning opportunity.

I'll read through more of the published patterns to align this one closer to the others.

I was having a conversation with @rrrutledge about what constitutes an approachable and useful pattern.

The patterns listed on the fearless change website are an interesting overlay to the patterns.

https://fearlessjourney.info/fearless-change-patterns/

I really like "Discover Your InnerSource" name for the pattern.

What do you think about the name?

How is this pattern related to other patterns like InnerSource Portal and Gig Marketplace?

Another great question to answer after defining the appropriate name and scope for this pattern.

Mar 06 '25 03:03 jeffabailey

@jeffabailey I took some liberties and added the checklist for maturity Structured to the initial message of this PR. That gives us some guidelines for the various things that we want to check before promoting this pattern to our book.

Apr 02 '25 17:04 spier

The biggest challenge I see in this pattern at the moment is the Solution section.

  * [Unified Source Code Inventory](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/source-code-inventory.md)

I agree this is a big challenge against this pattern.

Following the style guide:

don't use "InnerSource" in the name - all of these patterns are about InnerSource, so consider if using the term InnerSource makes it easier for potential readers to understand what this pattern is about. Note that there can also be good reasons to use InnerSource in the name as in "InnerSource License" for example.

We might change this pattern's name to "Discover Internal Code" or "Discover Internal Projects" which does have sections that overlap Unified Source Code Inventory (USCI).

I propose a rewrite to remove any overlapping concerns in USCI.

My friend Cursor gave me this comparison:

I'll help refine discover-your-innersource.md to focus on its unique aspects while removing overlap with source-code-inventory.md. Let me analyze the overlaps and propose changes:

Overlapping Concepts to Remove:

The general concept of finding internal code (covered in source-code-inventory.md)
The organizational-level inventory aspects
The dashboard/visualization aspects
The strategy framework aspects

Unique Aspects to Keep in discover-your-innersource.md:

The specific developer behavior and cultural aspects
The search engine implementation details
The process changes for developers
The communication channel aspects

Does this sound like a reasonable approach?

Apr 12 '25 00:04 jeffabailey

@jeffabailey this comparison on the unique and overlapping concepts is very helpful!

Could you also ask your friend Cursor for a comparison between this pattern and the InnerSource Portal pattern?

My current take one the unique ideas in each of these patterns:

InnerSource Portal - highlight key InnerSource projects, with a focus on highlighting projects that are actively promoting themselves as InnerSource
Unified Source Code Inventory - aggregate projects from various version control systems in a single place, no matter if they are closed source, InnerSource or open source
Discover your InnerSource - the behavioral changes required by developers to "look for InnerSource first" (described so well by Cursor!). maybe combined with the concierge service idea.

So maybe one could stay 1 and 2 are about tooling, while 3 is not?

The idea of providing actual search functionality would fit equally well in 1 and 2, wouldn't it? Neither of these patterns has been very explicit about how to set up a good search engine with a focus on InnerSource though. My suspicion is that most orgs re-use the search functionality of their VCS (github, gitlab, ...) to accomplish this. Some might use Backstage.

Apr 13 '25 18:04 spier

Sorry about the mess that I made with my last 3 commits. I was on the wrong branch. I cleaned it all up again (I hope), and committed those changes to #779 instead.

Apr 13 '25 18:04 spier

InnerSource Portal - highlight key InnerSource projects, with a focus on highlighting projects that are actively promoting themselves as InnerSource

Unified Source Code Inventory - aggregate projects from various version control systems in a single place, no matter if they are closed source, InnerSource or open source

Discover your InnerSource - the behavioral changes required by developers to "look for InnerSource first" (described so well by Cursor!). maybe combined with the concierge service idea.

Here's a comparison of concepts introduced in the three patterns using a custom GPT I created that sources our InnerSource Patterns and Managing InnerSource Projects book.

🧭 InnerSource Pattern Comparison Table

Concept	InnerSource Portal	Unified Source Code Inventory	Discover Your InnerSource	Best-Fit Pattern for Practitioner
Highlighting InnerSource projects	✅ Central function: promoting InnerSource visibility	❌ Not focused on promotion	🔸 Indirectly, via encouragement to explore	InnerSource Portal
Aggregating all source code (IS, closed, open)	🔸 May include some InnerSource projects	✅ Core purpose: unify all codebases	❌ Not applicable	Unified Source Code Inventory
Making InnerSource discoverable	✅ Projects curated for discoverability	✅ Through aggregation of all sources	✅ Cultural push to explore and adopt InnerSource	All (tech: Inventory & Portal; behavior: Discover)
Encouraging "InnerSource first" mindset	🔸 Reinforces via visibility	❌ Not focused on mindset	✅ Primary goal — shift developer behavior	Discover Your InnerSource
Concierge service / guided onboarding	❌ Not included	❌ Not included	✅ Often part of behavioral support (e.g., internal advocates)	Discover Your InnerSource
Cross-system code search	🔸 Might link out	✅ Key feature — aggregates across systems	❌ Not part of scope	Unified Source Code Inventory
Rewarding teams for InnerSource openness	✅ Visibility acts as incentive	❌ Does not emphasize recognition	🔸 Could be part of cultural change strategy	InnerSource Portal
Single entry point for exploring InnerSource	✅ Designed for this	🔸 Possible via UI aggregation	🔸 Encouraged behavior	InnerSource Portal
Supports culture change / developer behavior shift	🔸 Visibility aids change	❌ Purely technical	✅ Central goal — behavior and mindset change	Discover Your InnerSource

💡 Summary

InnerSource Portal: Best for visibility, promotion, and incentivizing InnerSource openness.
Unified Source Code Inventory: Best for technical aggregation and removing silos across repositories.
Discover Your InnerSource: Best for cultural transformation, onboarding support, and developer behavior change.

Here's the prompt I used to produce this table.


Compare these InnerSource Patterns and describe overlapping concepts while suggesting which pattern is most suited to contain individual concepts for an InnerSource practitioner.

Create a table.


 InnerSource Portal - highlight key InnerSource projects, with a focus on highlighting projects that are actively promoting themselves as InnerSource
   
 Unified Source Code Inventory - aggregate projects from various version control systems in a single place, no matter if they are closed source, InnerSource or open source
   
Discover your InnerSource - the behavioral changes required by developers to "look for InnerSource first" (described so well by Cursor!). maybe combined with the concierge service idea.

So maybe one could stay 1 and 2 are about tooling, while 3 is not?

That sounds reasonable. The table suggests that 3. is about culture and behavioral, and mindset changes. It seems the name of this pattern is moving toward "Promote Project Discovery" rather than "Discover Internal Code" or "Discover Internal Projects".

The idea of providing actual search functionality would fit equally well in 1 and 2, wouldn't it? Neither of these patterns has been very explicit about how to set up a good search engine with a focus on InnerSource though. My suspicion is that most orgs re-use the search functionality of their VCS (github, gitlab, ...) to accomplish this. Some might use Backstage.

It depends on if we want to make this pattern about behavior, tooling, or both.

Apr 17 '25 13:04 jeffabailey

This is really cool @jeffabailey . The comparison table with concepts, the 3 patterns, and the best-fit pattern is super helpful!

I have various thoughts about different aspects of this. I will reply in separate comments, so that it becomes easier to separate the conversations.

Apr 18 '25 11:04 spier

The way that you used AI support here is interesting. I have used ChatGPT for creating pattern drafts, but not for comparing patterns so yet.

Here's a comparison of concepts introduced in the three patterns using a custom GPT I created that sources our InnerSource Patterns and Managing InnerSource Projects book.

I looked at your ChatGPT prompt. How did you add InnerSource Patterns and Managing InnerSource Projects book as sources thought? I cannot see how that works in the prompt.

Apr 18 '25 11:04 spier

The comparison table is helpful for figuring out what the core focus of each of the existing patterns is, and how new patterns can add new insights to "fill the gaps" between the existing patterns.

I wonder if such overviews/comparisons could be published as a new content type in our InnerSource patterns book (or elsewhere). If I had to give such write-ups a name I might call it "scenario", "use case", or even just "article".

e.g. we could publish a scenario called "Enable project reuse". In that scenario we would incorporate the comparison table above, and point to patterns immediately related to the scenario (e.g. the 3 patterns that we are discussing here, and potentially others).

I will post that idea as a new issue, so that it can be discussed separate from this PR here.

Apr 18 '25 11:04 spier

I looked at your ChatGPT prompt. How did you add InnerSource Patterns and Managing InnerSource Projects book as sources thought? I cannot see how that works in the prompt.

I used using my ChatGPT account to create a custom GPT.

Clicking on the innersourcecommons.org config at the bottom of this image, I added this schema.

openapi: 3.1.0
info:
  title: InnerSource Commons Website API
  version: 1.0.0
  description: >
    Access content from the InnerSource Commons public website.
    This API allows retrieving pages and resources from the live website.
servers:
  - url: https://innersourcecommons.org
paths:
  /{path}:
    get:
      operationId: getWebsiteContent
      summary: Get content from the InnerSource Commons website
      parameters:
        - name: path
          in: path
          required: true
          description: >
            Path to a page or resource on the website
            (e.g. `about/privacy`, `learning/patterns`)
          schema:
            type: string
      responses:
        '200':
          description: Page content returned successfully
          content:
            text/html:
              schema:
                type: string
                description: HTML content of the page
        '404':
          description: Page not found
  /:
    get:
      operationId: getHomepage
      summary: Get the website homepage
      responses:
        '200':
          description: Homepage content returned successfully
          content:
            text/html:
              schema:
                type: string
                description: HTML content of the homepage

This uses https://innersourcecommons.org as a source.

The other config is for api.github.com, which navigates the GitHub API to pull information.

openapi: 3.1.0
info:
  title: InnerSource Commons GitHub API
  version: 1.1.1
  description: >
    Access structured content from InnerSource Commons repositories. Lists all content
    from both the Managing InnerSource Projects book and InnerSource Patterns repositories.
servers:
  - url: https://api.github.com/repos/InnerSourceCommons
    description: GitHub API endpoint for InnerSource Commons repositories
security:
  - github_auth: []
paths:
  /{repository}/contents:
    get:
      operationId: listRepositoryContents
      summary: List all repository content
      description: >
        Lists all content from the specified repository. Supports both the Managing InnerSource Projects
        book and InnerSource Patterns repositories. Returns metadata about each file including its path
        and download URL.
      parameters:
        - name: repository
          in: path
          required: true
          schema:
            type: string
            enum: [managing-innersource-projects, InnerSourcePatterns]
          description: The repository to list contents from
        - name: path
          in: query
          required: false
          schema:
            type: string
          description: The path to list contents from
        - name: ref
          in: query
          required: false
          schema:
            type: string
          description: The name of the commit/branch/tag
      responses:
        "200":
          description: A list of all repository content files
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GitHubContent"
        "404":
          description: Repository or content not found

components:
  schemas:
    GitHubContent:
      type: object
      properties:
        name:
          type: string
          description: The filename of the content
        path:
          type: string
          description: Full path to the content file
        sha:
          type: string
          description: The SHA of the content
        size:
          type: integer
          description: The size of the content
        url:
          type: string
          description: The API URL to fetch the content
        html_url:
          type: string
          description: GitHub web URL to view the content
        git_url:
          type: string
          description: The Git URL to fetch the content
        download_url:
          type: string
          description: Direct URL to download the raw content
          nullable: true
        type:
          type: string
          enum: [file, dir]
        _links:
          type: object
          properties:
            self:
              type: string
            git:
              type: string
            html:
              type: string

  securitySchemes:
    github_auth:
      type: http
      scheme: bearer
      description: GitHub API token for authentication

Apr 19 '25 00:04 jeffabailey

How to share and promote this in the community in general? Website/slack/etc? I wrote document with some background about scenarios that might be useful to fil with such a bot. Check it out in case it's useful: https://docs.google.com/document/d/1L08FcP6GLtyZxKkOc1QzHothR9kvBnqgG80YYkKBtgc/edit?tab=t.0#heading=h.12qwh2uatj32

May 05 '25 15:05 rrrutledge

@jeffabailey it has been some time since I looked at this PR, so I have forgotten a bit what we talked about before.

To confirm: You are pushing to get this pattern published in the book, right? i.e. get it to maturity structured?

I read the pattern again. My sense is that if we would focus this pattern on the behavior change only, then this might make things easier for us. If necessary, we can move elements from this pattern that relate to tooling into the InnerSource Portal pattern instead.

What do you think about that approach?

May 23 '25 17:05 spier

I read the pattern again. My sense is that if we would focus this pattern on the behavior change only, then this might make things easier for us. If necessary, we can move elements from this pattern that relate to tooling into the InnerSource Portal pattern instead.

What do you think about that approach?

Sounds like a good approach to me.

May 23 '25 23:05 jeffabailey