docs: examples: innersource: Org health and issue prioritization

[johnandersen777]

@yashlamba @sakshamarora1 and I talked about this last night in relation to @builtree

• https://patterns.innersourcecommons.org/
• https://intel.github.io/dffml/main/examples/innersource/index.html
  • In the 0.4.0 release this was called Software Portal - 2e42032
  • https://youtu.be/VogNhBMmsNk
• https://github.com/builtree/builtree/blob/main/governance/CHARTER.md
• https://github.com/builtree/builtree/blob/main/governance/GOVERNANCE.md
  • https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=10a29eb658b3039eccfa6f249da079194f535a9a
• https://github.com/builtree/builtree/blob/main/governance/STEERING-COMMITTEE.md

As a reminder, we are interested in InnerSource and the OpenSSF identifying security threats work (ietf-scitt/use-cases#14) being done in the open source community because it ties back to our initial mission with open source dependency security / maintainability analysis. This work also helps our project (dffml) as we scale out to understand how we can work more effectively across our plugins and the main package. This work also relates to coming up with ways to help the builtree organization scale and be more effective.

We talked about the existing InnerSource demos and how the goal of InnerSource as is it to enable more frequent changes of higher quality with increased reuse and contribution happening across an organization (such as builtree). We talked about how the one could use the CII best practices badging program as metrics, example.

Metrics can also be used to help projects get visibility so that others are aware of their feature sets when they need to reuse a project or aspects of a project. Feature set collection is also useful for analysis of what project efforts need to be joined/consolidated due to similar feature sets (for example the same set of functions in two python projects utils.py).

Metrics can also be about people, this person is at skill level 0-5 for JavaScript, our model could tell us that investing a mentors time in helping them learn JavaScript would accelerate development across projects faster than that mentor talking another issue. (Increase in overall production output, civilization terminology)

builtree has several projects which have potential cross project collaboration (we talked about dffml and the secret vault for the generic CI/CD work). Identification of feature sets helps determine where more opportunities for cross project collaboration exist. it also helps when contributors want to propose a new project, to identify if a similar project already exists. This ties into the inventory.

We talked about how investing in driving up metrics now (before GSoC season) will pay off big in terms of less manual review needing to be done and making contributors more autonomous and enabled to do great work (quality docs, tests, etc.).

We should consider creating some kind of org level health metrics. So that we can see the reuse and contribution happening from maintainers and contributors across projects (cross pollination, metric which describes health of set of projects, potentially the set of projects is the whole org).

We also talked about implementing InnerSource for an open source org could help senior folks in an org prioritize what they should work on when they have a role to help all the projects across the org when needed. Having this traceability and data on potential impact of work (this ties in with the estimating time to complete issue stuff from #1279) allows org admins / maintainers to make data driven decisions about what to work on. They will have a model to see that closing issue X increases throughput or quality, or both across all projects in the org by Y amount (time to close other issues shrinks) as estimated by the model / data flow.

---

The presentation we did at bsides pdx 2019 shows how we developed methodology for an event driven CI/CD pipeline which yielded insights into open source project maintenance and security posture. The work in this issue is a potential avenue to another presentation. One where we show how we continued work on our CI/CD + ML project to gather further insights on open source projects, including our own. Then though application on InnerSource principles within our orgs, we use those insights to build more effective organizations.

• What you're using
  • SBOM and Allowlist tool / presentation
• How you're using it
  • Data flow as standard architecture
• Should you be using it or something else
  • OpenSSF Metrics/Scorecard/S2C2F

[johnandersen777]

• Random idea: Detection of things which indicate a code base with large amounts of technical debt
  • It can be hard to measure what we want to see, sometimes we can measure the opposite of what we want to see and invert it

[johnandersen777]

• How can we incentivize reduction of technical debt?
  • How can we quantify technical debt due to duplicated feature sets?
    • Can we do it by quantifying it's inverse? By saying what would be the maximum amount of InnerSourceyness and how far we are away from that?

[johnandersen777]

• contribution: What are the dependencies?
  • Do we see authors from the downstream project showing up as contributors in their dependencies?
    • Filing issues?
    • In git log?

[johnandersen777]

GSoC project idea: Intuitive documentation practices as a vehicle for modular development

• Alternate title 0.0: Bridging the manager/developer communication gap
• Alternate title 1.1: Bridging the InnerSource engagement gap via intuitive documentation practices.
  • Alternate title 1.0: Bridging the InnerSource engagement gap via editable documentation.

[johnandersen777]

• https://github.com/blabla1337/skf-flask
• https://github.com/OWASP/common-requirement-enumeration

    graph TD

      subgraph system_context[System Context for Ideation]

        requirements_management[OWASP common-requirement-enumeration<br>&#91Software System&#93]
        data_storage[oras.land<br>&#91Software System&#93]
        source_control[Source Code Management Forgejo<br>&#91Software System&#93]
        engineer[Software Engineer<br>&#91Person&#93]
        manager[Project Manager<br>&#91Person&#93]
        project_idea[Project Idea THREATS.md + CONTRIBUTING.md<br>&#91Document&#93]
        ci_software[Continuous Integration<br>&#91Software System&#93]
        cd_software[Continuous Deployment<br>&#91Software System&#93]
        iaas[Infrastructure as a Service<br>&#91Software System&#93]

        project_idea -->|Understand requirements| requirements_management
        requirements_management --> manager
        manager -->|Communicate priority of tasks| engineer
        engineer --> source_control
        source_control --> ci_software
        data_storage -->|Pull dependencies from| ci_software
        iaas -->|Provide compute to| ci_software
        ci_software -->|Validated version| cd_software
        cd_software -->|Store copy| data_storage
        cd_software -->|Measure alignment to| project_idea

        class manager,engineer,project_idea Person;
        class innersource NewSystem;
        class ci_software,cd_software,requirements_management,source_control,data_storage,iaas ExistingSystem;

      end

      class system_context background;

Loading

[johnandersen777]

Map tags in github/gitlab/etc. via clustering models to understand which repos are which types of software. Then map to skills of developers to map workstreams for strategic efforts developers want to be involved in. Diff complexity.

• Data/metrics from UBSAN, ASAN, MSAN, compiler warnings.

[johnandersen777]

Idea: model projects as k8s resources vis kcp: https://github.com/kcp-dev

[johnandersen777]

https://cloud.google.com/architecture/devops/devops-process-team-experimentation

With regards to forcing a single way of doing things on teams - 'This approach only helps poorly run teams - to some extent. Well-run teams typically play along with the process theatre, but try to keep their old way of working. If they can. If they cannot: their output + motivation drops. [...] "The same way “no one is fired for buying IBM”, it’s true that “no one is fired for introducing Scrum/SAFe”. But better engineers/managers sure do leave because of it: to places where team autonomy is a given. Take away autonomy: you’ll never have a world-class engineering team."' - https://mobile.twitter.com/GergelyOrosz/status/1519948934457831431

How does InnerSource relate to this? InnerSource facilitates discovery of team experimentation success stories and provides BKMs which enable easy leveraging of wins across teams. InnerSource is our methodology for actively seeking out and proliferating team successes. It is also the way we measuring the impact of this methodology itself.

[johnandersen777]

@dffml.config
class BadgeURLConfig:
    tiers: Dict[str, str] = field.config(
        "Mapping of state to URLs for .svg badge",
        default_factory=lambda: {
            True: "https://img.shields.io/badge/Maintainance-Active-green",
            False: "https://img.shields.io/badge/Maintainance-Inactive-red",
        }
    )

[johnandersen777]

Explore definition of ALIGNMENT.md, did a search (https://duckduckgo.com/?q=inpath%3AALIGNMENT.md%E2%80%8B&t=canonical&ia=web) and looks like someone did one: https://github.com/confidential-containers/documentation/blob/main/ALIGNMENT.md

This is a very text based lenses into what we want to do, probbaly links to repos, maybe even built of the strategic direction which THREATS.md shows.

---

• THREATS.md
  • What does the code really do
• ALIGNMENT.md
  • Who/what are we working with to take our current state and make it into our desired state
• STRATEGY.md
  • What is our desired state / objectives for why this code exists and what other KPIs/OKRs this code should drive

---

The above look closely related to Alice, aka the system context, aka the upstream the overlay and the orchestrator, the past, the present and the future

• Upstream
  • Past
• Overlay
  • Present
• Orchestration
  • Takes us to the future

[johnandersen777]

• https://codeberg.org/ForgeFed/ForgeFed/src/branch/main/rdf/context.jsonld
• https://codeberg.org/ForgeFed/ForgeFed/src/branch/main/resources.md
  • Smart to list external resource owners
• https://codeberg.org/SocialCoding/sc-guild/issues/2
  • Sounds very similar to @builtree
• https://codeberg.org/forgejo/discussions/issues/12
  • CI/CD Event Federation

[johnandersen777]

Upstream First Development in Federated Software Forges

prompt(model:gpt-4o): Explain what upstream first is: Explain how federation of software forges (such as gitea and gitlab and github, similar to how threads and mastodon federate via activitypub) which form ad-hoc organizations in pursuit of shared strategic principles and plans can practice upstream first development using github pull request style workflow. Return your response as a markdown file which will be included in the documentation for the forgejo project. Please go into detail. https://chatgpt.com/share/bc6fc7c3-aa76-4518-9d41-0d5107b92f52

Introduction

In a federated environment where various software forges like Gitea, GitLab, and GitHub interact similarly to social platforms like Threads and Mastodon via ActivityPub, the practice of "upstream first" development can be efficiently managed. This document outlines how these federated forges can form ad-hoc organizations to pursue shared strategic principles and plans while adhering to the upstream first development model using a GitHub pull request style workflow.

Key Concepts

Federation of Software Forges

Federation allows independent software forges to communicate and collaborate seamlessly. Each forge retains its autonomy while contributing to a larger ecosystem. This is similar to how social networks federate, enabling users from different platforms to interact. Federation in the context of software development means:

• Interoperability: Different forges can work together, sharing code and issues.
• Decentralization: Each forge operates independently but can contribute to and pull from a common pool of projects.
• Collaboration: Developers from different forges can collaborate on the same project as if they were using the same platform.

Upstream First Development

This development practice involves contributing changes, enhancements, or bug fixes to the original project (upstream) before integrating them into downstream projects or forks. It promotes:

• Shared Improvement: Enhancements benefit all users of the upstream project.
• Simplified Maintenance: Reduces the need for maintaining separate patches.
• Better Collaboration: Encourages cooperation between developers.
• Avoiding Divergence: Keeps downstream projects aligned with upstream changes.

Workflow for Upstream First Development

1. Identify and Plan the Change

Shared Strategic Principles and Plans

Federated forges often form ad-hoc organizations to pursue common goals. These organizations should identify strategic principles and plans guiding their development efforts. These principles might include:

• Open Collaboration: Encouraging contributions from any developer in the federation.
• Transparency: Keeping development discussions and decisions open and accessible.
• Quality and Security: Ensuring that all contributions meet high standards for quality and security.

Issue Tracking

Use a federated issue tracking system to identify and discuss the change needed. Each forge can contribute to the discussion regardless of where the issue was originally reported. This can be managed through:

• Federated Issue Boards: A shared space where issues from all participating forges are tracked and prioritized.
• Discussion Threads: Forums or discussion threads where developers can propose solutions and collaborate on ideas.

2. Develop the Change

Local Development

Developers work on their local forks or branches of the project. Ensure the changes align with the upstream project's guidelines and standards. Best practices include:

• Consistent Coding Standards: Adhering to the coding guidelines of the upstream project.
• Unit Tests: Writing tests to ensure the change works as intended.
• Documentation: Updating documentation to reflect the changes.

Collaborative Effort

Utilize federation capabilities to collaborate with developers across different forges. Tools like federated code review and discussion can be beneficial here. Techniques include:

• Pair Programming: Working together with developers from different forges.
• Federated Code Reviews: Using tools that allow for code reviews across different forges.

3. Submit a Pull Request (PR)

Upstream Repository

Once the change is ready, submit a pull request to the upstream repository. This is done in the forge where the original project is hosted. Key steps include:

• Fork and Branch: Fork the upstream repository and create a branch for your changes.
• Commit Changes: Ensure each commit is clear and concise.
• Open PR: Open a pull request with a detailed description of the changes.

Federated PRs

Federated forges should support cross-forge pull requests, allowing a pull request from a repository on one forge to be reviewed and merged into a repository on another forge. This involves:

• Federated Pull Request Tools: Tools that allow PRs to be initiated from any forge and integrated with the upstream project.
• ActivityPub Integration: Using protocols like ActivityPub to manage communication between forges.

4. Review and Collaborate

Code Review

Engage in a thorough code review process. Federated forges can allow reviewers from different platforms to comment and approve changes. Best practices include:

• Multiple Reviewers: Ensure the PR is reviewed by multiple developers.
• Automated Testing: Use CI/CD to run automated tests on the PR.
• Feedback Loop: Address feedback promptly and update the PR as necessary.

Continuous Integration

Utilize CI/CD pipelines that work across federated environments to ensure changes meet quality standards. This involves:

• Federated CI/CD Tools: CI/CD tools that can pull code from different forges and run tests.
• Integration Tests: Running comprehensive integration tests to ensure the change works across all environments.

5. Merge and Integrate

Upstream Merge

Once the pull request is approved, it is merged into the upstream project. This ensures the change benefits the entire community. Steps include:

• Final Review: A final review by the maintainers.
• Merge: Using a merge strategy that maintains a clean commit history.

Downstream Synchronization

Downstream projects can then pull the latest changes from the upstream project. This keeps all forks and derivatives up-to-date with the latest improvements. This involves:

• Regular Updates: Downstream projects should regularly pull changes from upstream.
• Conflict Resolution: Address any conflicts that arise during the merge.

6. Communication and Documentation

Federated Communication

Use federated communication tools to keep all stakeholders informed about the progress and integration of changes. This includes:

• Announcements: Announcing major changes and updates across all forges.
• Discussion Forums: Maintaining forums or chat channels for ongoing communication.

Documentation Updates

Ensure that any changes are well-documented. Documentation should be accessible across all federated forges. This involves:

• Documentation PRs: Submitting PRs to update documentation alongside code changes.
• Shared Documentation Repositories: Repositories that aggregate documentation from different forges.

Benefits of This Workflow

• Shared Improvements: Contributions benefit the entire ecosystem, not just individual forges.
• Reduced Maintenance Burden: By integrating changes upstream first, the need for maintaining separate patches and re-integration efforts is minimized.
• Enhanced Collaboration: Federated tools and workflows foster better collaboration across different platforms.
• Consistency: Ensures all projects derived from the upstream source remain consistent and compatible.

Conclusion

By adopting an upstream first development practice in a federated environment, software forges can collaborate more effectively and ensure that improvements benefit the broader community. This workflow, modeled on the GitHub pull request style, leverages the strengths of federation to create a more cohesive and high-quality software development ecosystem.

For more details on federation and how to get involved, visit the Forgejo Project.