Skip to main content

Working with Organic

Organic CMS architecture and workflows have been established to grant autonomy to customer engineers and contributors while preserving the stability of the Organic CMS product. This document discusses the basics of the architecture, each team’s ownership of development tasks, and the workflow for reporting bugs, requesting features, and proposing code changes to the organic-content repository.

Architecture​

Customer engineers are given access to site-specific repositories in order to make frontend and business-specific backend changes. With this architecture, site-specific changes can be released in accordance with each client’s specific timelines and approval processes.

Each domain fully integrated with Organic CMS (including the headless backend and DevOps management) has two relevant repositories: the backend plugin and the headless frontend. In addition, enterprise clients may have access to an additional backend plugin repository that impacts more than one domain across their business (commonly referred to as an “organization” repository).

Requests for changes to the core Organic CMS codebase (the organic-content repository) must be submitted to Organic for review and approval. It is recommended that contributors propose these changes to Organic before beginning development work to obtain preliminary concept approval. Organic reserves the right to approve, reject, or request modification of any client or third-party code contributions. Approved changes will be released by Organic according to their internal procedures, with or without prior notice to the original contributor. Release timing exceptions may be made for client contributions that have external dependencies if communicated to Organic in advance.

Ownership of tasks​

Clients have autonomy to pursue their own changes, feature additions, and bug fixes. In addition, most client contracts also have dedicated engineering support hours, which can be used to ask Organic to troubleshoot integrations, add new fields or blocks, or make elements of the offering configurable for client-side replacement. Requests of this nature should be made through the Organic Support email address (support@organic.ly) or via the Organic Help Desk.

Customer engineers and Organic engineers have ownership of different aspects of site maintenance as follows:

Customer engineers own:

  • Site-specific frontend changes or redesigns
  • Site-specific block creation
  • Site-specific bugs
  • Site-specific scripts
  • Ads integration with non-Organic ad providers
  • Google Tag Manager changes (excluding consent management changes when CMP relationship is managed by Organic)
  • Third-party integrations, including Google Analytics
  • Updating the latest Organic CMS versions on their own timelines, at the domain level

Organic owns:

  • Platform-wide new blocks, features, and improvements
  • Platform-wide bug resolution
  • Organic Ads integration
  • CMP changes when Organic handles consent management
  • Updates and versioning for key, required plugins like Yoast
  • Accepting or rejecting all proposed changes to organic-content repo made by customer engineers
  • For DevOps clients: CDN-level changes

Workflow​

Reporting bugs​

When reporting bugs, clients should first engage with their own engineering teams for troubleshooting. If the bug is related to one of that team’s areas of ownership, the bug should be handled directly by that engineering team and should not be escalated to Organic.

If the client’s engineering team determines that the bug needs to be addressed in the Organic CMS core platform, the bug should be escalated to Organic via the Organic Support email address (support@organic.ly) or the Organic Help Desk. The bug will be prioritized by Organic engineers on the basis of urgency and impact.

Requesting new features​

If a client’s editorial, business, or leadership teams would like to request new features for Organic CMS, those can be submitted via the Organic Support email address (support@organic.ly) or the Organic Help Desk. New feature requests will be considered for development by the Organic CMS team and may be adopted into the product roadmap. New features that Organic does not choose to pursue at the platform level can often be accomplished at the site-specific level by the client’s engineering team.

Proposing changes to organic-content repository or CDN configurations​

From time to time, customer engineers may wish to propose changes to the Organic CMS core or their CDN settings, neither of which are open to adjustment without Organic review.

In those cases, here is the process:

  1. Client submits proposal via the Organic Support email address (support@organic.ly) or the Organic Help Desk, including relevant information like the reason for the request, the changes to be made, where the changes would be made, and whether they would prefer to have their engineers code the solution or would like Organic engineers to handle. Preferred dates for these changes to be implemented should also be included if the request is time-bound.

  2. Proposals will be reviewed by Organic, who will approve/reject the proposal or request additional information. Approved requests do not guarantee delivery by requested date and clients are encouraged to work with their engineering team for extremely time-sensitive changes if they can be made in client-specific repositories.

  3. If Organic will be making the code change, the request will be added to their queue and prioritized against other tasks. If the change will be handled by customer engineers, Organic engineers will provide feedback once a pull request is available for review: approval will be given for code changes that meet Organic CMS goals and standards, and in some cases, recommendations may be given to customer engineers to put the changes on a different repository, or to make certain changes to make the changes more performant.

Creating and managing pull requests​

To maintain an efficient and streamlined pull request (PR) workflow for Organic CMS core, we have established a set of guidelines for creating and managing PRs. For the latest version of these guidelines, please visit our documentation in GitHub.