From 0c96c20be841858ca479eb540590369868029425 Mon Sep 17 00:00:00 2001 From: Amburi Roy Date: Thu, 28 Aug 2025 13:51:19 +0200 Subject: [PATCH 01/21] feat: create new structure pattern ai-code-generation-context --- README.md | 1 + .../ai-code-generation-context.md | 161 ++++++++++++++++++ 2 files changed, 162 insertions(+) create mode 100644 patterns/2-structured/ai-code-generation-context.md diff --git a/README.md b/README.md index 5b1f8a590..08ccca526 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,7 @@ Our mission * [Standard Release Process](patterns/2-structured/release-process.md) - *Teams may hesitate to adopt an InnerSource project if they are unsure of its maturity. To address this, consistent release notes and published artifacts are crucial. These practices showcase a strong dedication to the project, instilling confidence and assuring users of ongoing commitment to sustainable and well-managed software.* * [Group Support](patterns/2-structured/group-support.md) - *What happens if a team or individual no longer supports an InnerSource project? Keep the project alive by forming a group of interested individuals.* * [Explicit Governance Levels](patterns/2-structured/governance-levels.md) - *Different teams within an organization use InnerSource practices in varying ways, leading to confusion and inefficiencies due to inconsistent expectations of collaboration and contribution rights. Establish centrally documented governance levels that define the extent of influence contributing teams can have on a project, improving clarity for contributors and host teams alike.* +* [AI Code Generation Context](patterns/2-structured/ai-code-generation-context.md) - *AI tools generate code that diverges from project standards and architectural patterns. Provide an AI Code Generation Context Package within repositories to guide AI tools in producing contributions that align with existing project conventions, reducing review friction and maintaining code consistency.* ### Maturity Level 1: Initial diff --git a/patterns/2-structured/ai-code-generation-context.md b/patterns/2-structured/ai-code-generation-context.md new file mode 100644 index 000000000..b7b37ea46 --- /dev/null +++ b/patterns/2-structured/ai-code-generation-context.md @@ -0,0 +1,161 @@ +## Title + +AI Code Generation Context + +## Patlet + +AI tools generate code that diverges from project standards and architectural patterns. Provide an AI Code Generation Context Package within repositories to guide AI tools in producing contributions that align with existing project conventions, reducing review friction and maintaining code consistency. + +## Problem + +With the growing use of AI tools (like GitHub Copilot, ChatGPT, or custom LLMs), InnerSource contributors are increasingly using generative AI to write code. However, without project-specific context, these tools often produce code that diverges from the project's architectural patterns, naming conventions, or quality standards. This leads to friction during reviews, inconsistent codebases, and technical debts or additional burden on maintainers. + +## Context + +* InnerSource adoption is in place across the organization +* Developers are encouraged to use AI tools to improve productivity +* Contributors may not be familiar or failed to prompt meticulously while generating code through AI with the target codebase's idioms, architecture, or constraints +* Maintainers want to empower contributors using AI while preserving code consistency and maintainability +* Multiple teams are contributing to shared repositories with varying levels of familiarity with project standards +* Code review processes are becoming bottlenecked by AI-generated code that requires significant rework + +## Forces + +* **AI Model Limitations**: AI models generate code based on generalized training data, not project-specific patterns, leading to generic solutions that may not fit the project's architecture +* **Knowledge Gap**: New contributors using AI tools might unknowingly bypass existing architectural norms, coding standards, and established patterns +* **Review Overhead**: AI-assisted PRs can significantly increase review load if not aligned with existing practices, as maintainers must spend time explaining and correcting deviations +* **Productivity vs. Quality Trade-off**: While AI tools boost individual productivity, they can reduce overall team productivity if the generated code requires extensive rework +* **Context Switching Cost**: Developers benefit from AI tools only when they have the right contextual grounding, but manually providing this context for each AI interaction is time-consuming +* **Inconsistent Standards**: Different AI tools and different prompting approaches by contributors can lead to wildly inconsistent code styles and patterns +* **Maintenance Burden**: Creating and maintaining comprehensive AI context requires ongoing effort from maintainers +* **Tool Integration Complexity**: Different AI tools have different ways of consuming context, making it challenging to create universal guidance +* **AI Tool Cost Constraints**: Comprehensive AI context increases processing costs (AI tools charge based on "tokens" * units of text measurement) and usage limits, requiring strategic balance between context completeness and efficiency + +## Solution + +Provide an **AI Code Generation Context Package** within the repository to guide AI tools in producing contributions that align with project standards. This package serves as a comprehensive reference that contributors can easily provide to AI tools to ensure generated code follows project conventions. + +### Implementation Structure + +Create a `innersource-ai/` folder in the repository root containing: + +#### Core Documentation Files (Required) + +`PROMPT.md`: Project-specific instructions for AI tools +* Naming conventions (variables, functions, classes, files) +* Logging patterns and error handling approaches +* Testing strategy and preferred testing frameworks +* Code formatting and style preferences +* Common anti-patterns to avoid +* Preferred libraries and frameworks for specific tasks + +`ARCHITECTURE.md`: Lightweight system overview +* High-level system architecture and component relationships +* Data flow patterns and API design principles +* Dependency management guidelines +* Module organization and layering principles +* Integration patterns with external systems + +`STYLE_GUIDE.md`: Comprehensive coding guidelines +* Language-specific style rules +* Code organization patterns +* Documentation standards +* Performance considerations +* Security guidelines and common vulnerabilities to avoid + +#### Optional Enhancements (Implement As Needed) + +##### Practical Examples + +`EXAMPLES/`: Sample code files demonstrating best practices +* `good-examples/`: Well-written code snippets with explanations +* `bad-examples/`: Common mistakes with explanations of why they're problematic +* `refactoring-examples/`: Before/after code showing proper improvements +* Template files for common patterns (controllers, services, utilities) + +##### Configuration and Tooling + +`CONFIG/`: Shared formatter and analysis configurations +* `.prettierrc`, `.eslintrc`, or equivalent formatting configs +* `.editorconfig` for consistent editor settings +* Static analysis tool configurations +* Pre-commit hook configurations + +`INTEGRATION/`: AI tool-specific integration guides +* GitHub Copilot workspace configuration +* Custom GPT instructions and prompts +* IDE plugin configurations +* CLI tool integration examples + +##### Advanced Features + +`EMBEDDINGS/` (Optional): For advanced LLM integrations +* Searchable knowledge base of project patterns +* Vector embeddings of code examples +* Semantic search capabilities for finding relevant patterns + +### Implementation Strategy + +**Context Efficiency**: Start with core documentation files (~1000 words of context) to balance context value with AI tool costs. Expand strategically based on measured impact on review cycles and code quality. + +### Usage Patterns + +#### For Contributors +* **Before Starting**: Review the AI context package to understand project standards +* **During Development**: Reference specific files when prompting AI tools +* **Code Generation**: Include relevant context snippets in AI prompts +* **Validation**: Use provided examples to verify AI-generated code aligns with standards + +#### For AI Tool Integration +* **Direct Reference**: Copy relevant sections into AI tool prompts +* **URL Integration**: Reference files via repository URLs in AI tools that support web access +* **IDE Integration**: Configure AI plugins to automatically include context +* **Custom Workflows**: Integrate context into CI/CD pipelines for automated validation + +### Maintenance Strategy + +* **Version Control**: Track changes to AI context alongside code changes +* **Regular Updates**: Review and update context as project standards evolve +* **Community Contribution**: Allow contributors to suggest improvements to AI context +* **Metrics Tracking**: Monitor the effectiveness of AI context through code review metrics + +## Resulting Context + +* **Improved Code Quality**: AI-assisted contributions become consistent with existing code standards and architectural patterns from the first submission +* **Reduced Review Friction**: Maintainers can trust incoming PRs more readily, significantly reducing review fatigue and time-to-merge +* **Enhanced Contributor Experience**: Contributors using AI produce better, more maintainable code even on their first attempts, leading to increased confidence and participation +* **Scalable Collaboration**: Opens the door to scalable, AI-aware InnerSource collaboration across teams without sacrificing code quality +* **Knowledge Preservation**: Project knowledge becomes more explicit and accessible, reducing dependency on tribal knowledge +* **Faster Onboarding**: New contributors can leverage AI tools effectively from day one, reducing the learning curve for project-specific patterns +* **Consistent Evolution**: As AI tools improve, the context package ensures that enhanced capabilities are channeled toward project-appropriate solutions + +## Rationale + +This pattern addresses the fundamental mismatch between AI tools' general training and project-specific requirements. By providing structured, easily consumable context, we enable AI tools to generate code that feels like it was written by an experienced project contributor rather than an outsider. + +The `innersource-ai/` folder approach is intentionally explicit and discoverable, making it clear to both humans and AI tools where to find project-specific guidance. The modular structure allows teams to implement incrementally, starting with basic style guides and expanding to more sophisticated examples and configurations as needed. + +This solution balances the productivity benefits of AI tools with the quality requirements of professional software development, creating a sustainable approach to AI-assisted InnerSource collaboration. + +## Known Instances + +To be added. + +## Status + +* Structured +* Drafted in August 2025 + +## Author + +[Amburi Roy](https://www.linkedin.com/in/amburi/) + +## Related Patterns + +* [Standard Base Documentation](../base-documentation.md) - Provides the foundation documentation that AI context builds upon +* [InnerSource Portal](../innersource-portal.md) - Could include AI context availability as searchable metadata for project discovery +* [Trusted Committer](../trusted-committer.md) - Trusted Committers are responsible for maintaining and evolving the AI context package + +## License + +This pattern is licensed under the Creative Commons Attribution 4.0 International License. From 3ef88fb241354ffc7f655e8a8dfbff4af49a3781 Mon Sep 17 00:00:00 2001 From: Amburi Roy Date: Fri, 29 Aug 2025 09:19:16 +0200 Subject: [PATCH 02/21] chore: moved the pattern to initial folder --- README.md | 2 +- .../{2-structured => 1-initial}/ai-code-generation-context.md | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename patterns/{2-structured => 1-initial}/ai-code-generation-context.md (100%) diff --git a/README.md b/README.md index 08ccca526..27cf89411 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ Our mission * [Standard Release Process](patterns/2-structured/release-process.md) - *Teams may hesitate to adopt an InnerSource project if they are unsure of its maturity. To address this, consistent release notes and published artifacts are crucial. These practices showcase a strong dedication to the project, instilling confidence and assuring users of ongoing commitment to sustainable and well-managed software.* * [Group Support](patterns/2-structured/group-support.md) - *What happens if a team or individual no longer supports an InnerSource project? Keep the project alive by forming a group of interested individuals.* * [Explicit Governance Levels](patterns/2-structured/governance-levels.md) - *Different teams within an organization use InnerSource practices in varying ways, leading to confusion and inefficiencies due to inconsistent expectations of collaboration and contribution rights. Establish centrally documented governance levels that define the extent of influence contributing teams can have on a project, improving clarity for contributors and host teams alike.* -* [AI Code Generation Context](patterns/2-structured/ai-code-generation-context.md) - *AI tools generate code that diverges from project standards and architectural patterns. Provide an AI Code Generation Context Package within repositories to guide AI tools in producing contributions that align with existing project conventions, reducing review friction and maintaining code consistency.* +* [AI Code Generation Context](patterns/1-initial/ai-code-generation-context.md) - *AI tools generate code that diverges from project standards and architectural patterns. Provide an AI Code Generation Context Package within repositories to guide AI tools in producing contributions that align with existing project conventions, reducing review friction and maintaining code consistency.* ### Maturity Level 1: Initial diff --git a/patterns/2-structured/ai-code-generation-context.md b/patterns/1-initial/ai-code-generation-context.md similarity index 100% rename from patterns/2-structured/ai-code-generation-context.md rename to patterns/1-initial/ai-code-generation-context.md From 1815c5cd568a885119d319dfa7a55a7f249b62ec Mon Sep 17 00:00:00 2001 From: Amburi Roy Date: Fri, 29 Aug 2025 09:21:15 +0200 Subject: [PATCH 03/21] chore: remove the known instances as it's initial pattern --- patterns/1-initial/ai-code-generation-context.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/patterns/1-initial/ai-code-generation-context.md b/patterns/1-initial/ai-code-generation-context.md index b7b37ea46..2159d5e31 100644 --- a/patterns/1-initial/ai-code-generation-context.md +++ b/patterns/1-initial/ai-code-generation-context.md @@ -137,10 +137,6 @@ The `innersource-ai/` folder approach is intentionally explicit and discoverable This solution balances the productivity benefits of AI tools with the quality requirements of professional software development, creating a sustainable approach to AI-assisted InnerSource collaboration. -## Known Instances - -To be added. - ## Status * Structured From 3ba7faac13443450c9fd9de4d09dd023e44a0451 Mon Sep 17 00:00:00 2001 From: Amburi Roy Date: Fri, 29 Aug 2025 13:55:46 +0200 Subject: [PATCH 04/21] fix: update the links --- patterns/1-initial/ai-code-generation-context.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/patterns/1-initial/ai-code-generation-context.md b/patterns/1-initial/ai-code-generation-context.md index 2159d5e31..cc124e29c 100644 --- a/patterns/1-initial/ai-code-generation-context.md +++ b/patterns/1-initial/ai-code-generation-context.md @@ -148,9 +148,9 @@ This solution balances the productivity benefits of AI tools with the quality re ## Related Patterns -* [Standard Base Documentation](../base-documentation.md) - Provides the foundation documentation that AI context builds upon -* [InnerSource Portal](../innersource-portal.md) - Could include AI context availability as searchable metadata for project discovery -* [Trusted Committer](../trusted-committer.md) - Trusted Committers are responsible for maintaining and evolving the AI context package +* [Standard Base Documentation](../2-structured/base-documentation.md) - Provides the foundation documentation that AI context builds upon +* [InnerSource Portal](../2-structured/innersource-portal.md) - Could include AI context availability as searchable metadata for project discovery +* [Trusted Committer](../2-structured/trusted-committer.md) - Trusted Committers are responsible for maintaining and evolving the AI context package ## License From 4efaf04f4dc282c88b3e6484d69631ddf579f720 Mon Sep 17 00:00:00 2001 From: Amburi Roy Date: Fri, 29 Aug 2025 14:11:24 +0200 Subject: [PATCH 05/21] fix: md linting --- .../1-initial/ai-code-generation-context.md | 149 ++++++++++-------- 1 file changed, 79 insertions(+), 70 deletions(-) diff --git a/patterns/1-initial/ai-code-generation-context.md b/patterns/1-initial/ai-code-generation-context.md index cc124e29c..f011e4dc5 100644 --- a/patterns/1-initial/ai-code-generation-context.md +++ b/patterns/1-initial/ai-code-generation-context.md @@ -12,24 +12,24 @@ With the growing use of AI tools (like GitHub Copilot, ChatGPT, or custom LLMs), ## Context -* InnerSource adoption is in place across the organization -* Developers are encouraged to use AI tools to improve productivity -* Contributors may not be familiar or failed to prompt meticulously while generating code through AI with the target codebase's idioms, architecture, or constraints -* Maintainers want to empower contributors using AI while preserving code consistency and maintainability -* Multiple teams are contributing to shared repositories with varying levels of familiarity with project standards -* Code review processes are becoming bottlenecked by AI-generated code that requires significant rework + - InnerSource adoption is in place across the organization + - Developers are encouraged to use AI tools to improve productivity + - Contributors may not be familiar or failed to prompt meticulously while generating code through AI with the target codebase's idioms, architecture, or constraints + - Maintainers want to empower contributors using AI while preserving code consistency and maintainability + - Multiple teams are contributing to shared repositories with varying levels of familiarity with project standards + - Code review processes are becoming bottlenecked by AI-generated code that requires significant rework ## Forces -* **AI Model Limitations**: AI models generate code based on generalized training data, not project-specific patterns, leading to generic solutions that may not fit the project's architecture -* **Knowledge Gap**: New contributors using AI tools might unknowingly bypass existing architectural norms, coding standards, and established patterns -* **Review Overhead**: AI-assisted PRs can significantly increase review load if not aligned with existing practices, as maintainers must spend time explaining and correcting deviations -* **Productivity vs. Quality Trade-off**: While AI tools boost individual productivity, they can reduce overall team productivity if the generated code requires extensive rework -* **Context Switching Cost**: Developers benefit from AI tools only when they have the right contextual grounding, but manually providing this context for each AI interaction is time-consuming -* **Inconsistent Standards**: Different AI tools and different prompting approaches by contributors can lead to wildly inconsistent code styles and patterns -* **Maintenance Burden**: Creating and maintaining comprehensive AI context requires ongoing effort from maintainers -* **Tool Integration Complexity**: Different AI tools have different ways of consuming context, making it challenging to create universal guidance -* **AI Tool Cost Constraints**: Comprehensive AI context increases processing costs (AI tools charge based on "tokens" * units of text measurement) and usage limits, requiring strategic balance between context completeness and efficiency + - **AI Model Limitations**: AI models generate code based on generalized training data, not project-specific patterns, leading to generic solutions that may not fit the project's architecture + - **Knowledge Gap**: New contributors using AI tools might unknowingly bypass existing architectural norms, coding standards, and established patterns + - **Review Overhead**: AI-assisted PRs can significantly increase review load if not aligned with existing practices, as maintainers must spend time explaining and correcting deviations + - **Productivity vs. Quality Trade-off**: While AI tools boost individual productivity, they can reduce overall team productivity if the generated code requires extensive rework + - **Context Switching Cost**: Developers benefit from AI tools only when they have the right contextual grounding, but manually providing this context for each AI interaction is time-consuming + - **Inconsistent Standards**: Different AI tools and different prompting approaches by contributors can lead to wildly inconsistent code styles and patterns + - **Maintenance Burden**: Creating and maintaining comprehensive AI context requires ongoing effort from maintainers + - **Tool Integration Complexity**: Different AI tools have different ways of consuming context, making it challenging to create universal guidance + - **AI Tool Cost Constraints**: Comprehensive AI context increases processing costs (AI tools charge based on "tokens" \* units of text measurement) and usage limits, requiring strategic balance between context completeness and efficiency ## Solution @@ -42,57 +42,64 @@ Create a `innersource-ai/` folder in the repository root containing: #### Core Documentation Files (Required) `PROMPT.md`: Project-specific instructions for AI tools -* Naming conventions (variables, functions, classes, files) -* Logging patterns and error handling approaches -* Testing strategy and preferred testing frameworks -* Code formatting and style preferences -* Common anti-patterns to avoid -* Preferred libraries and frameworks for specific tasks + + - Naming conventions (variables, functions, classes, files) + - Logging patterns and error handling approaches + - Testing strategy and preferred testing frameworks + - Code formatting and style preferences + - Common anti-patterns to avoid + - Preferred libraries and frameworks for specific tasks `ARCHITECTURE.md`: Lightweight system overview -* High-level system architecture and component relationships -* Data flow patterns and API design principles -* Dependency management guidelines -* Module organization and layering principles -* Integration patterns with external systems + + - High-level system architecture and component relationships + - Data flow patterns and API design principles + - Dependency management guidelines + - Module organization and layering principles + - Integration patterns with external systems `STYLE_GUIDE.md`: Comprehensive coding guidelines -* Language-specific style rules -* Code organization patterns -* Documentation standards -* Performance considerations -* Security guidelines and common vulnerabilities to avoid + + - Language-specific style rules + - Code organization patterns + - Documentation standards + - Performance considerations + - Security guidelines and common vulnerabilities to avoid #### Optional Enhancements (Implement As Needed) ##### Practical Examples `EXAMPLES/`: Sample code files demonstrating best practices -* `good-examples/`: Well-written code snippets with explanations -* `bad-examples/`: Common mistakes with explanations of why they're problematic -* `refactoring-examples/`: Before/after code showing proper improvements -* Template files for common patterns (controllers, services, utilities) + + - `good-examples/`: Well-written code snippets with explanations + - `bad-examples/`: Common mistakes with explanations of why they're problematic + - `refactoring-examples/`: Before/after code showing proper improvements + - Template files for common patterns (controllers, services, utilities) ##### Configuration and Tooling `CONFIG/`: Shared formatter and analysis configurations -* `.prettierrc`, `.eslintrc`, or equivalent formatting configs -* `.editorconfig` for consistent editor settings -* Static analysis tool configurations -* Pre-commit hook configurations + + - `.prettierrc`, `.eslintrc`, or equivalent formatting configs + - `.editorconfig` for consistent editor settings + - Static analysis tool configurations + - Pre-commit hook configurations `INTEGRATION/`: AI tool-specific integration guides -* GitHub Copilot workspace configuration -* Custom GPT instructions and prompts -* IDE plugin configurations -* CLI tool integration examples + + - GitHub Copilot workspace configuration + - Custom GPT instructions and prompts + - IDE plugin configurations + - CLI tool integration examples ##### Advanced Features `EMBEDDINGS/` (Optional): For advanced LLM integrations -* Searchable knowledge base of project patterns -* Vector embeddings of code examples -* Semantic search capabilities for finding relevant patterns + + - Searchable knowledge base of project patterns + - Vector embeddings of code examples + - Semantic search capabilities for finding relevant patterns ### Implementation Strategy @@ -101,33 +108,35 @@ Create a `innersource-ai/` folder in the repository root containing: ### Usage Patterns #### For Contributors -* **Before Starting**: Review the AI context package to understand project standards -* **During Development**: Reference specific files when prompting AI tools -* **Code Generation**: Include relevant context snippets in AI prompts -* **Validation**: Use provided examples to verify AI-generated code aligns with standards + + - **Before Starting**: Review the AI context package to understand project standards + - **During Development**: Reference specific files when prompting AI tools + - **Code Generation**: Include relevant context snippets in AI prompts + - **Validation**: Use provided examples to verify AI-generated code aligns with standards #### For AI Tool Integration -* **Direct Reference**: Copy relevant sections into AI tool prompts -* **URL Integration**: Reference files via repository URLs in AI tools that support web access -* **IDE Integration**: Configure AI plugins to automatically include context -* **Custom Workflows**: Integrate context into CI/CD pipelines for automated validation + + - **Direct Reference**: Copy relevant sections into AI tool prompts + - **URL Integration**: Reference files via repository URLs in AI tools that support web access + - **IDE Integration**: Configure AI plugins to automatically include context + - **Custom Workflows**: Integrate context into CI/CD pipelines for automated validation ### Maintenance Strategy -* **Version Control**: Track changes to AI context alongside code changes -* **Regular Updates**: Review and update context as project standards evolve -* **Community Contribution**: Allow contributors to suggest improvements to AI context -* **Metrics Tracking**: Monitor the effectiveness of AI context through code review metrics + - **Version Control**: Track changes to AI context alongside code changes + - **Regular Updates**: Review and update context as project standards evolve + - **Community Contribution**: Allow contributors to suggest improvements to AI context + - **Metrics Tracking**: Monitor the effectiveness of AI context through code review metrics ## Resulting Context -* **Improved Code Quality**: AI-assisted contributions become consistent with existing code standards and architectural patterns from the first submission -* **Reduced Review Friction**: Maintainers can trust incoming PRs more readily, significantly reducing review fatigue and time-to-merge -* **Enhanced Contributor Experience**: Contributors using AI produce better, more maintainable code even on their first attempts, leading to increased confidence and participation -* **Scalable Collaboration**: Opens the door to scalable, AI-aware InnerSource collaboration across teams without sacrificing code quality -* **Knowledge Preservation**: Project knowledge becomes more explicit and accessible, reducing dependency on tribal knowledge -* **Faster Onboarding**: New contributors can leverage AI tools effectively from day one, reducing the learning curve for project-specific patterns -* **Consistent Evolution**: As AI tools improve, the context package ensures that enhanced capabilities are channeled toward project-appropriate solutions + - **Improved Code Quality**: AI-assisted contributions become consistent with existing code standards and architectural patterns from the first submission + - **Reduced Review Friction**: Maintainers can trust incoming PRs more readily, significantly reducing review fatigue and time-to-merge + - **Enhanced Contributor Experience**: Contributors using AI produce better, more maintainable code even on their first attempts, leading to increased confidence and participation + - **Scalable Collaboration**: Opens the door to scalable, AI-aware InnerSource collaboration across teams without sacrificing code quality + - **Knowledge Preservation**: Project knowledge becomes more explicit and accessible, reducing dependency on tribal knowledge + - **Faster Onboarding**: New contributors can leverage AI tools effectively from day one, reducing the learning curve for project-specific patterns + - **Consistent Evolution**: As AI tools improve, the context package ensures that enhanced capabilities are channeled toward project-appropriate solutions ## Rationale @@ -139,8 +148,8 @@ This solution balances the productivity benefits of AI tools with the quality re ## Status -* Structured -* Drafted in August 2025 + - Structured + - Drafted in August 2025 ## Author @@ -148,9 +157,9 @@ This solution balances the productivity benefits of AI tools with the quality re ## Related Patterns -* [Standard Base Documentation](../2-structured/base-documentation.md) - Provides the foundation documentation that AI context builds upon -* [InnerSource Portal](../2-structured/innersource-portal.md) - Could include AI context availability as searchable metadata for project discovery -* [Trusted Committer](../2-structured/trusted-committer.md) - Trusted Committers are responsible for maintaining and evolving the AI context package + - [Standard Base Documentation](../2-structured/base-documentation.md): Provides the foundation documentation that AI context builds upon + - [InnerSource Portal](../2-structured/innersource-portal.md): Could include AI context availability as searchable metadata for project discovery + - [Trusted Committer](../2-structured/trusted-committer.md): Trusted Committers are responsible for maintaining and evolving the AI context package ## License From 0930e217391b3494e1d4ed9c2d8caec4782d93a1 Mon Sep 17 00:00:00 2001 From: Amburi Roy Date: Sat, 30 Aug 2025 19:35:38 +0200 Subject: [PATCH 06/21] feat: Update the pattern doc to address the review comments. --- .../1-initial/ai-code-generation-context.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/patterns/1-initial/ai-code-generation-context.md b/patterns/1-initial/ai-code-generation-context.md index f011e4dc5..8950fa281 100644 --- a/patterns/1-initial/ai-code-generation-context.md +++ b/patterns/1-initial/ai-code-generation-context.md @@ -12,12 +12,12 @@ With the growing use of AI tools (like GitHub Copilot, ChatGPT, or custom LLMs), ## Context - - InnerSource adoption is in place across the organization - - Developers are encouraged to use AI tools to improve productivity - - Contributors may not be familiar or failed to prompt meticulously while generating code through AI with the target codebase's idioms, architecture, or constraints - - Maintainers want to empower contributors using AI while preserving code consistency and maintainability - - Multiple teams are contributing to shared repositories with varying levels of familiarity with project standards - - Code review processes are becoming bottlenecked by AI-generated code that requires significant rework + - InnerSource adoption is in place across the organisation. + - Developers are encouraged to use AI tools to improve their productivity. + - Contributors may not be familiar with or fail to meticulously prompt when generating code through AI, using the target codebase's idioms, architecture, or constraints. + - Maintainers want to empower contributors using AI while preserving code consistency and maintainability. + - Multiple teams are contributing to shared repositories with varying levels of familiarity with project standards. + - Code review processes are becoming bottlenecked by AI-generated code that requires significant rework. ## Forces @@ -27,17 +27,17 @@ With the growing use of AI tools (like GitHub Copilot, ChatGPT, or custom LLMs), - **Productivity vs. Quality Trade-off**: While AI tools boost individual productivity, they can reduce overall team productivity if the generated code requires extensive rework - **Context Switching Cost**: Developers benefit from AI tools only when they have the right contextual grounding, but manually providing this context for each AI interaction is time-consuming - **Inconsistent Standards**: Different AI tools and different prompting approaches by contributors can lead to wildly inconsistent code styles and patterns - - **Maintenance Burden**: Creating and maintaining comprehensive AI context requires ongoing effort from maintainers + - **Maintenance Burden**: Creating and maintaining the comprehensive AI context requires ongoing effort from maintainers - **Tool Integration Complexity**: Different AI tools have different ways of consuming context, making it challenging to create universal guidance - **AI Tool Cost Constraints**: Comprehensive AI context increases processing costs (AI tools charge based on "tokens" \* units of text measurement) and usage limits, requiring strategic balance between context completeness and efficiency ## Solution -Provide an **AI Code Generation Context Package** within the repository to guide AI tools in producing contributions that align with project standards. This package serves as a comprehensive reference that contributors can easily provide to AI tools to ensure generated code follows project conventions. +Provide an **AI Code Generation Context** folder within the repository to guide AI tools in producing contributions that align with project standards. This folder serves as a comprehensive reference that contributors can easily provide to AI tools, ensuring that generated code adheres to project conventions. ### Implementation Structure -Create a `innersource-ai/` folder in the repository root containing: +Create an `innersource-ai/` folder in the repository root containing: #### Core Documentation Files (Required) @@ -55,18 +55,18 @@ Create a `innersource-ai/` folder in the repository root containing: - High-level system architecture and component relationships - Data flow patterns and API design principles - Dependency management guidelines - - Module organization and layering principles + - Module organisation and layering principles - Integration patterns with external systems `STYLE_GUIDE.md`: Comprehensive coding guidelines - Language-specific style rules - - Code organization patterns + - Code organisation patterns - Documentation standards - Performance considerations - Security guidelines and common vulnerabilities to avoid -#### Optional Enhancements (Implement As Needed) +#### Enhancements (Optional) ##### Practical Examples @@ -95,16 +95,16 @@ Create a `innersource-ai/` folder in the repository root containing: ##### Advanced Features -`EMBEDDINGS/` (Optional): For advanced LLM integrations +`EMBEDDINGS/`: For advanced LLM integrations - Searchable knowledge base of project patterns - Vector embeddings of code examples - Semantic search capabilities for finding relevant patterns -### Implementation Strategy - **Context Efficiency**: Start with core documentation files (~1000 words of context) to balance context value with AI tool costs. Expand strategically based on measured impact on review cycles and code quality. +**Naming Convension**: The suggested file and folder names follow industry common practices. However, codebase owners may choose alternative names that are more discoverable and relatable to their specific project or codebase. Any chosen naming convention should be clearly documented and communicated to contributors through proper documentation. + ### Usage Patterns #### For Contributors @@ -148,7 +148,7 @@ This solution balances the productivity benefits of AI tools with the quality re ## Status - - Structured + - Initial - Drafted in August 2025 ## Author From f67991fdb804c3a3eebd293a6e3c48f879204250 Mon Sep 17 00:00:00 2001 From: Sebastian Spier Date: Thu, 28 Aug 2025 23:55:27 +0200 Subject: [PATCH 07/21] Fix markdownlint issues --- .../1-initial/ai-code-generation-context.md | 80 +++++++++---------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/patterns/1-initial/ai-code-generation-context.md b/patterns/1-initial/ai-code-generation-context.md index 8950fa281..974e6c0fd 100644 --- a/patterns/1-initial/ai-code-generation-context.md +++ b/patterns/1-initial/ai-code-generation-context.md @@ -43,28 +43,28 @@ Create an `innersource-ai/` folder in the repository root containing: `PROMPT.md`: Project-specific instructions for AI tools - - Naming conventions (variables, functions, classes, files) - - Logging patterns and error handling approaches - - Testing strategy and preferred testing frameworks - - Code formatting and style preferences - - Common anti-patterns to avoid - - Preferred libraries and frameworks for specific tasks +* Naming conventions (variables, functions, classes, files) +* Logging patterns and error handling approaches +* Testing strategy and preferred testing frameworks +* Code formatting and style preferences +* Common anti-patterns to avoid +* Preferred libraries and frameworks for specific tasks `ARCHITECTURE.md`: Lightweight system overview - - High-level system architecture and component relationships - - Data flow patterns and API design principles - - Dependency management guidelines - - Module organisation and layering principles - - Integration patterns with external systems +* High-level system architecture and component relationships +* Data flow patterns and API design principles +* Dependency management guidelines +* Module organization and layering principles +* Integration patterns with external systems `STYLE_GUIDE.md`: Comprehensive coding guidelines - - Language-specific style rules - - Code organisation patterns - - Documentation standards - - Performance considerations - - Security guidelines and common vulnerabilities to avoid +* Language-specific style rules +* Code organization patterns +* Documentation standards +* Performance considerations +* Security guidelines and common vulnerabilities to avoid #### Enhancements (Optional) @@ -72,34 +72,34 @@ Create an `innersource-ai/` folder in the repository root containing: `EXAMPLES/`: Sample code files demonstrating best practices - - `good-examples/`: Well-written code snippets with explanations - - `bad-examples/`: Common mistakes with explanations of why they're problematic - - `refactoring-examples/`: Before/after code showing proper improvements - - Template files for common patterns (controllers, services, utilities) +* `good-examples/`: Well-written code snippets with explanations +* `bad-examples/`: Common mistakes with explanations of why they're problematic +* `refactoring-examples/`: Before/after code showing proper improvements +* Template files for common patterns (controllers, services, utilities) ##### Configuration and Tooling `CONFIG/`: Shared formatter and analysis configurations - - `.prettierrc`, `.eslintrc`, or equivalent formatting configs - - `.editorconfig` for consistent editor settings - - Static analysis tool configurations - - Pre-commit hook configurations +* `.prettierrc`, `.eslintrc`, or equivalent formatting configs +* `.editorconfig` for consistent editor settings +* Static analysis tool configurations +* Pre-commit hook configurations `INTEGRATION/`: AI tool-specific integration guides - - GitHub Copilot workspace configuration - - Custom GPT instructions and prompts - - IDE plugin configurations - - CLI tool integration examples +* GitHub Copilot workspace configuration +* Custom GPT instructions and prompts +* IDE plugin configurations +* CLI tool integration examples ##### Advanced Features -`EMBEDDINGS/`: For advanced LLM integrations +`EMBEDDINGS/` (Optional): For advanced LLM integrations - - Searchable knowledge base of project patterns - - Vector embeddings of code examples - - Semantic search capabilities for finding relevant patterns +* Searchable knowledge base of project patterns +* Vector embeddings of code examples +* Semantic search capabilities for finding relevant patterns **Context Efficiency**: Start with core documentation files (~1000 words of context) to balance context value with AI tool costs. Expand strategically based on measured impact on review cycles and code quality. @@ -109,17 +109,17 @@ Create an `innersource-ai/` folder in the repository root containing: #### For Contributors - - **Before Starting**: Review the AI context package to understand project standards - - **During Development**: Reference specific files when prompting AI tools - - **Code Generation**: Include relevant context snippets in AI prompts - - **Validation**: Use provided examples to verify AI-generated code aligns with standards +* **Before Starting**: Review the AI context package to understand project standards +* **During Development**: Reference specific files when prompting AI tools +* **Code Generation**: Include relevant context snippets in AI prompts +* **Validation**: Use provided examples to verify AI-generated code aligns with standards #### For AI Tool Integration - - **Direct Reference**: Copy relevant sections into AI tool prompts - - **URL Integration**: Reference files via repository URLs in AI tools that support web access - - **IDE Integration**: Configure AI plugins to automatically include context - - **Custom Workflows**: Integrate context into CI/CD pipelines for automated validation +* **Direct Reference**: Copy relevant sections into AI tool prompts +* **URL Integration**: Reference files via repository URLs in AI tools that support web access +* **IDE Integration**: Configure AI plugins to automatically include context +* **Custom Workflows**: Integrate context into CI/CD pipelines for automated validation ### Maintenance Strategy From 7da3ec80fef987ad60f257ad11c2a383c015d09e Mon Sep 17 00:00:00 2001 From: Sebastian Spier Date: Fri, 29 Aug 2025 00:07:36 +0200 Subject: [PATCH 08/21] Removing the license text from pattern. Context: The license is the same for all patterns contributed to our repo, hence removing the mention of the license from the pattern itself. --- patterns/1-initial/ai-code-generation-context.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/patterns/1-initial/ai-code-generation-context.md b/patterns/1-initial/ai-code-generation-context.md index 974e6c0fd..8e047c138 100644 --- a/patterns/1-initial/ai-code-generation-context.md +++ b/patterns/1-initial/ai-code-generation-context.md @@ -157,10 +157,6 @@ This solution balances the productivity benefits of AI tools with the quality re ## Related Patterns - - [Standard Base Documentation](../2-structured/base-documentation.md): Provides the foundation documentation that AI context builds upon - - [InnerSource Portal](../2-structured/innersource-portal.md): Could include AI context availability as searchable metadata for project discovery - - [Trusted Committer](../2-structured/trusted-committer.md): Trusted Committers are responsible for maintaining and evolving the AI context package - -## License - -This pattern is licensed under the Creative Commons Attribution 4.0 International License. +* [Standard Base Documentation](../base-documentation.md) - Provides the foundation documentation that AI context builds upon +* [InnerSource Portal](../innersource-portal.md) - Could include AI context availability as searchable metadata for project discovery +* [Trusted Committer](../trusted-committer.md) - Trusted Committers are responsible for maintaining and evolving the AI context package From 979b0a116812d1d62e43eef089579cdc27b34406 Mon Sep 17 00:00:00 2001 From: Sebastian Spier Date: Fri, 29 Aug 2025 12:50:21 +0200 Subject: [PATCH 09/21] Moving to the Inital section in the main overview --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 27cf89411..42247f040 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,6 @@ Our mission * [Standard Release Process](patterns/2-structured/release-process.md) - *Teams may hesitate to adopt an InnerSource project if they are unsure of its maturity. To address this, consistent release notes and published artifacts are crucial. These practices showcase a strong dedication to the project, instilling confidence and assuring users of ongoing commitment to sustainable and well-managed software.* * [Group Support](patterns/2-structured/group-support.md) - *What happens if a team or individual no longer supports an InnerSource project? Keep the project alive by forming a group of interested individuals.* * [Explicit Governance Levels](patterns/2-structured/governance-levels.md) - *Different teams within an organization use InnerSource practices in varying ways, leading to confusion and inefficiencies due to inconsistent expectations of collaboration and contribution rights. Establish centrally documented governance levels that define the extent of influence contributing teams can have on a project, improving clarity for contributors and host teams alike.* -* [AI Code Generation Context](patterns/1-initial/ai-code-generation-context.md) - *AI tools generate code that diverges from project standards and architectural patterns. Provide an AI Code Generation Context Package within repositories to guide AI tools in producing contributions that align with existing project conventions, reducing review friction and maintaining code consistency.* ### Maturity Level 1: Initial @@ -97,6 +96,7 @@ Our mission * [InnerSource Incentives and Disincentives](/patterns/1-initial/incentives-and-disincentives.md) - *Lack of awareness for incentives as well well as disincentives for InnerSource contribution decrease the chances of an InnerSource project receiving contributions; this is addressed by sharing a comprehensive list of potential incentives and disincentives.* * [Walk the InnerSource talk](/patterns/1-initial/walk-the-innersource-talk.md) - *Teams across the organization are encouraged to adopt InnerSource principles such as working openly, sharing code, and collaborating transparently. But, if the team behind the InnerSource initiative doesn’t follow these practices themselves, it undermines credibility and adoption. Therefore, this team should lead by example: documenting their decisions as code, working in the open, and treating their work as an InnerSource project to build trust and show others how it’s done.* * [Require InnerSource before Open Source](/patterns/1-initial/innersource-before-open-source.md) - *Maintaining and managing open source projects can be challenging for organizations, due to a lack of internal infrastructure and people with the knowledge of the required collaboration practices. By requiring projects to be InnerSource before becoming open source, teams have time to establish the necessary internal support, governance, and collaboration skills needed for successful community engagement.* +* [AI Code Generation Context](patterns/1-initial/ai-code-generation-context.md) - *AI tools generate code that diverges from project standards and architectural patterns. Provide an AI Code Generation Context Package within repositories to guide AI tools in producing contributions that align with existing project conventions, reducing review friction and maintaining code consistency.*