Contribution model
This is the central guide on how to contribute to CivicTheme, be it code or design.
Last updated
This is the central guide on how to contribute to CivicTheme, be it code or design.
Last updated
Contributing to CivicTheme follows a clear process to ensure that all additions meet community and technical standards. This guide will help you understand the various levels of contributions—small, medium, and major—along with the associated requirements and steps for each.
Before you start contributing to CivicTheme, review our contribution model. This model shows you how to consider your contributions so that they can be routed and managed properly.
CivicTheme welcomes contributions in various forms, from small enhancements to more complex components. The process is designed to assess whether an existing component fulfils the needs, or if a new contribution is necessary. Contributions are categorised into three levels:
This document outlines each level of contribution and provides guidance on how to determine the most appropriate level for your proposed changes.
A small contribution typically involves minimal changes, such as small adjustments to existing components or minor bug fixes. This type of contribution is most often used when:
A solution already exists in the component library.
The existing component can be easily extended with minimal code changes.
Minimal documentation: Provide a brief description of the change, what it fixes or improves, and any references to related issues. User guides will be updated, including compliance, security, or research sections.
Testing: Ensure your changes do not break existing functionality. Provide tests or manual testing instructions, and ensure you've thoroughly tested prior to submitting.
Code quality: Maintain consistent code style with the existing CivicTheme codebase.
If a component or solution already exists and only minor tweaks are needed.
If the functionality of a component is extended without affecting its broader use.
Fixing a CSS alignment issue on an existing button.
Adding a small utility class to a component for accessibility.
Follow the basic contribution guidelines and submit your pull request (PR) via GitHub.
Reference related issues or discussions if applicable.
A medium contribution is necessary when your proposed changes require extending an existing component or creating a new feature that addresses a specific need but does not yet have a broader application.
Documentation: Provide a detailed explanation of the contribution, including use cases, and reference designs or discussions.
Testing: Provide thorough test cases to ensure the contribution works in all expected environments, ensuring you've tested your changes prior to submitting.
Broader Use: Clarify if the new feature can evolve for wider usage across the CivicTheme system.
If the existing component cannot be extended easily and requires more significant changes.
If others can potentially reuse the new feature, but it is initially being built for a specific purpose.
Adding a new input field type to the form component with validation.
Creating a new, reusable layout option for a specific website section.
Provide more detailed documentation in the PR, explaining the purpose and broader application possibilities.
Ensure full test coverage and reference any designs or issues.
Submit via GitHub with a link to the related issue or proposal.
Major contributions involve significant changes to CivicTheme, such as new components, removing existing features, or altering fundamental design principles. These changes require broader community discussion and approval through the .
When to use the RFC process for major contributions:
Introducing new components or patterns.
Adding new API surface areas or modifying major existing APIs.
Removing features already released.
Creating new conventions or design principles.
Comprehensive documentation: A detailed breakdown of the problem, proposed solution, and how the contribution fits into the broader CivicTheme structure. Include mockups, wireframes, or other design assets if applicable.
Broader use: Ensure the new component is designed with reuse in mind, following design principles that support various use cases across the system.
Extensive testing: Rigorous testing in various environments and edge cases is required to ensure the component is robust and can be maintained. Please provide test cases that reviewers can test as well.
If there is no existing component or solution that can be easily extended or adapted.
If the new component is expected to be used broadly across different applications or sites.
Creating an entirely new navigation component for CivicTheme.
Proposing a large design system change that requires updates to multiple components.
Open a discussion in the CivicTheme community forums, Drupal.org, or GitHub discussions to gather feedback before coding begins.
Submit a detailed proposal and follow the community approval process.
Once approved, develop the contribution, ensuring thorough documentation and testing before submitting a PR on GitHub.
In some cases, a solution may only be applicable to a single website or application. In such instances, hardcoding the solution directly may be more efficient than contributing a reusable component. However, whenever possible, contributions should aim for reusability within the broader CivicTheme ecosystem.
When a solution is too specific to be reused across other projects or cannot be made generic.
Adding a one-off feature or custom styling for a single website section that does not fit CivicTheme's broader design principles.
By following this guide, you can ensure your contributions to CivicTheme are aligned with the project's goals and community standards. Contributions, whether small or large, help improve the system and provide value to all CivicTheme users.
Ensure you follow the appropriate process based on the type of contribution you're making and provide all necessary documentation and testing before submitting your work.
We're always looking at ways to improve our model for contributions, and rely on your feedback to ensure an enjoyable contribution experience. The best way to give us feedback is to join our Slack channel and chat to us there, or contact us via email!
