A ChatGPT About Drupal Conventional Commits

Intro

I have implemented Semantic Releases and an autogenerated Change Log into Drupal projects. The effort has surprised me at times, thinking about what a commit message should be categorized as, whether it should be noted in the change log, how and whether it affects a release version bump, and whether it is appropriate to squash merge requests.

Since I haven't found any forum posts, issues, or articles on this problem space as it relates to CMSs generally and to Drupal projects specifically, I decided to pick ChatGPT's brain on the subject. The following is the result of this conversation.

A Chat About Drupal Conventional Commits

Me:

What are conventional commits?

ChatGPT

Conventional Commits is a specification for structuring commit messages in a standardized way. The idea is to make it easier for developers to understand the purpose and context of a commit, and to automate certain parts of the software development process, such as generating changelogs or triggering automatic deployments.

A conventional commit message consists of a header, a body, and a footer. The header includes a type, a scope, and a subject, which together describe the change being made. The body and footer are optional and provide additional information about the change.

The type of a commit message is a keyword that specifies the general nature of the change. For example, the type might be "feat" for a new feature, "fix" for a bug fix, or "docs" for documentation updates. The scope is optional and is used to further specify the location or component of the change, such as a specific file or module.

Here's an example of a conventional commit message:

feat(authentication): add support for OAuth2 authentication

This commit adds support for OAuth2 authentication using the Google API.

BREAKING CHANGE: The previous authentication method has been removed.
In this example, the type is "feat", the scope is "authentication", and the subject is "add support for OAuth2 authentication". The body provides additional details about the change, and the footer includes a "BREAKING CHANGE" section indicating that the change is backwards-incompatible.

By following the Conventional Commits specification, developers can ensure that their commit messages are consistent, informative, and machine-readable, making it easier to collaborate and automate certain parts of the software development process.

Me:

I can see how this can be useful to autogenerate a change log. That might work for libraries or packages. But, is this applicable to web applications and content management systems?

ChatGPT

Yes, Conventional Commits can be used for web applications and content management systems as well, especially if they are built using a version control system such as Git.

In web development, changes to the codebase can have a direct impact on the user experience, and it's important to be able to communicate those changes effectively to users, stakeholders, and other developers. By using a standardized commit message format, such as Conventional Commits, developers can provide more context and clarity around the changes they are making, which can help reduce confusion and improve collaboration.

For example, if a developer is working on a web application and makes a change to the login process, they might use a commit message like this:

feat(login): add support for two-factor authentication

This commit adds support for two-factor authentication to the login process, improving security for users.

BREAKING CHANGE: Users will need to set up two-factor authentication before logging in.

This message makes it clear that the change is related to the login process, what the change is (adding two-factor authentication), why the change is important (improving security), and any breaking changes that might affect users (they will need to set up two-factor authentication before logging in).

By using Conventional Commits, developers can create commit messages that are consistent, informative, and easy to understand, making it easier to collaborate and manage changes to web applications and content management systems.

Me:

Semantic Release is an NPM package with plugins that can generate release notes based on commit messages. By default, it treats breaking changes as major, feature enhancements as minor, and bug fixes as patch releases. Angular has its own set of conventional commit types for web applications. What are some appropriate commit types for a CMS? And how might each affect the release version?

ChatGPT

The appropriate commit types for a CMS will depend on the specific features and functionality of the CMS, but here are some common types of commits that may be applicable:

feat: This commit type can be used for new features or functionality added to the CMS. Depending on the significance of the feature, it could result in a minor or major release.

fix: This commit type can be used for bug fixes within the CMS. This would typically result in a patch release.

docs: This commit type can be used for documentation changes, such as updating the user manual or adding inline comments. This type of commit would not usually affect the release version.

style: This commit type can be used for changes to the look and feel of the CMS, such as updating the CSS or layout. This type of commit would not usually affect the release version.

refactor: This commit type can be used for code changes that do not add any new functionality or fix any bugs, but are done for other reasons such as improving code readability or maintainability. This type of commit would not usually affect the release version.

test: This commit type can be used for changes to the testing infrastructure, such as adding new unit tests or fixing broken tests. This type of commit would not usually affect the release version.

In terms of how each type of commit might affect the release version, it would depend on the specific rules and guidelines set by the CMS development team. Typically, breaking changes would result in a major release, new features would result in a minor release, and bug fixes would result in a patch release. However, this may vary depending on the significance of the changes and the development team's release management process.

Me:

Do style, docs, refactor, and test types typically affect the release version?

ChatGPT

In general, commit types like style, docs, refactor, and test are not expected to have a significant impact on the release version of a project. These commit types are typically considered as non-breaking changes, as they don't add new features, fix bugs, or change the behavior of the software.

However, in some cases, these types of changes may indirectly impact the release version. For example:

style: Changes to the style or formatting of the code may affect the behavior of the software, particularly if there are syntax errors introduced. While unlikely, it's possible that such changes may require a patch release.

docs: Changes to documentation are usually independent of the software functionality and shouldn't affect the release version, unless the documentation is incorrect, incomplete, or unclear and is causing issues for the users.

refactor: Changes to code structure, organization, or naming conventions don't usually change the functionality of the software, but in some cases, they may indirectly impact the behavior of the software. For example, refactoring may remove duplicate code, which could affect performance or memory usage.

test: Changes to the test suite shouldn't impact the release version, as long as they don't introduce new bugs or issues that are not caught during the testing phase.

Ultimately, the decision of whether a particular commit should trigger a release or not depends on the project's specific release management process and guidelines. The release manager should consider the impact of each commit on the software, the severity of the changes, and the project's release schedule to decide whether a new release is necessary or not.

Me:

So, the default behavior from Semantic Release's plugin should be configured to treat each type's release version change as appropriate for the project. The Drupal ecosystem has a number of possible software projects associated with it: modules, NPM packages, composer packages, etc. When each is developed independently, I can see how semantic versioning and commit types can be used very clearly. It is not so clear for Drupal CMS projects as a whole. A CMS project has several types of end users and stake holders. If the change log is meant to communicate to editors and possibly site visitors, what conventional commit types do you think might be most appropriate?

ChatGPT

For Drupal CMS projects that are meant to be used by multiple types of end users and stakeholders, the commit types should be selected carefully to ensure that the release notes are easy to understand and useful for all stakeholders. Here are some commit types that might be most appropriate:

feat: This commit type can be used for new features or functionality that are relevant to end users or stakeholders. For example, adding a new content type or user role could be considered a feature that should be communicated to stakeholders.

fix: This commit type can be used for bug fixes that are relevant to end users or stakeholders. For example, fixing a broken link or resolving a permission issue could be considered a fix that should be communicated to stakeholders.

docs: This commit type can be used for changes to documentation that are relevant to end users or stakeholders. For example, updating the user manual or adding inline help text could be considered a documentation change that should be communicated to stakeholders.

style: This commit type can be used for changes to the look and feel of the CMS that are relevant to end users or stakeholders. For example, updating the color scheme or typography could be considered a style change that should be communicated to stakeholders.

refactor: This commit type can be used for code changes that improve the CMS's performance, security, or maintainability, which may not be immediately visible to end users but still have an impact on their experience. For example, optimizing database queries or refactoring legacy code could be considered a refactor that should be communicated to stakeholders.

chore: This commit type can be used for changes to the build process, dependencies, or other non-functional aspects of the CMS that are relevant to developers or site administrators. For example, upgrading to a new version of PHP or updating a third-party library could be considered a chore that should be communicated to stakeholders.

Ultimately, the choice of commit types depends on the specific features and functionality of the CMS and the priorities of its stakeholders. The goal should be to provide clear and concise release notes that communicate the changes in a way that is relevant and useful to all stakeholders.

Me:

What about development specific features? For example, we are adding a set of modules and configurations for local development of a data migration. This doesn't affect editors or site visitors, but lays the groundwork for developers to begin building custom data migration tools. What commit type seems most appropriate here?

ChatGPT

For development-specific features like adding modules and configurations for local development of a data migration, the most appropriate commit type would be feat, as it represents the addition of new features or functionality. Specifically, you could use a prefix to distinguish the commit as being relevant to developers only, such as dev-feat or internal-feat. This communicates to stakeholders that the commit is related to a feature that is only relevant to the development team, and not to end users or site visitors.

While this commit type may not directly impact the CMS's end users or stakeholders, it is still important to communicate these changes in the release notes to keep everyone informed and up-to-date with the progress of the project. This also helps to build transparency and trust within the development team and with external stakeholders who may be interested in the project's development process.

Me:

Should a refactor affect the release version--major, minor, patch, or none?

ChatGPT

Whether a refactor should affect the release version depends on the scope and impact of the changes made. In general, refactors that have a significant impact on the functionality or stability of the codebase should result in a version change. However, if the refactor only improves the code quality or maintainability without changing the external behavior of the system, then it might not require a version change.

If the refactor introduces new features or breaks existing ones, it should result in a major version change. If it includes performance improvements or adds functionality in a backward-compatible way, it should result in a minor version change. If the refactor only fixes bugs or includes small improvements, it should result in a patch version change.

It's important to note that the decision to increment the version number should be made based on the impact of the refactor on the external behavior of the system, rather than the effort put into the refactor. The version number should accurately reflect the changes made and the impact they have on the system.

Me:

How can we tell semantic release to treat refactor commits differently?

ChatGPT

To tell Semantic Release to treat refactor commits differently, you can use a custom configuration for the @semantic-release/commit-analyzer plugin. This plugin is responsible for analyzing the commit messages and determining the appropriate version number to assign to the release. By default, it treats refactors as patch releases, but you can customize this behavior by configuring the plugin to consider refactor commits as minor or major releases instead.

To do this, you can use the "preset" option in your semantic-release configuration file and specify a custom commit message preset that defines how refactor commits should be handled. For example, you could create a custom preset that treats refactor commits as minor releases by adding the following to your configuration file:

{
  "preset": "angular",
  "plugins": [
    "@semantic-release/commit-analyzer",
    {
      "preset": "angular",
      "releaseRules": [
        {"type": "refactor", "release": "minor"}
      ]
    },
    "@semantic-release/release-notes-generator",
    "@semantic-release/github"
  ]
}

In this configuration, we're using the "angular" preset as a base, which defines the default behavior for commit types. Then, we're configuring the commit analyzer plugin to consider refactor commits as minor releases by adding a custom release rule that matches commits with the "refactor" type and sets the release type to "minor".

With this configuration, Semantic Release will assign a minor version number to any release that includes a commit with the "refactor" type, as long as there are no other breaking changes or major features included in the release.

Me:

Are there any commits that should skip a release version change?

ChatGPT

Yes, there are certain types of commits that may not require a release version change. For example, commits that only update documentation, code formatting, comments, or other non-functional changes that don't impact the system's behavior or features may not need to trigger a new release version.

In general, any commit that doesn't add new functionality or modify existing functionality in a significant way could be considered a candidate for skipping a release version change. However, it's ultimately up to the project team to decide which types of commits should trigger a version change and which should not.

It's worth noting that skipping a release version change for certain commits can be a useful strategy for avoiding unnecessary version number increments, especially for projects with frequent releases or small changes. This can help to prevent confusion among users and stakeholders who may expect major version increments to signal significant changes or new features. On the other hand, if a commit does impact the system's behavior or features in a meaningful way, it's important to update the version number accordingly to ensure clarity and transparency.

Me:

When is it appropriate to bump a major version of a CMS website? Is it appropriate to consider removing a feature a breaking change? This is not an API, it's a web application provided to editors in order to communicate with site visitors. What might be considered a breaking change for a CMS website? Should the site's major version only be bumped if a strong visual or organizational change is made?

ChatGPT

In a CMS website, it's appropriate to bump a major version when there are significant changes that affect the overall functionality, usability, or compatibility of the website. Some examples of changes that might warrant a major version bump include:

• Removing a core feature that is widely used by site editors or visitors
• Changing the way that content is structured or displayed, such as reorganizing menus or changing the layout of pages
• Upgrading to a new major version of the CMS software itself, which may introduce significant changes to the underlying architecture or APIs

In general, any change that significantly impacts the user experience or requires significant effort for editors or developers to adapt to could be considered a candidate for a major version bump.

Regarding removing a feature, it depends on the feature itself and how widely it is used. If it's a core feature that many editors or visitors rely on, removing it could be considered a breaking change. However, if it's a less frequently used feature or one that can be replaced with a similar feature, it may not be necessary to consider it a breaking change.

It's important to communicate any breaking changes clearly to editors and other stakeholders and to provide guidance on how to adapt to the changes. In some cases, it may be appropriate to provide a transitional period where both the old and new features are available, to allow users to adjust at their own pace.

As for when to bump the major version of the site, it's ultimately up to the project team to decide based on the scope and impact of the changes being made. If there are strong visual or organizational changes that significantly affect the user experience or require a significant amount of effort to adapt to, then it may be appropriate to bump the major version. However, if the changes are more incremental or focused on bug fixes and minor enhancements, it may be more appropriate to bump the minor or patch version instead.

Conclusion

This was a fun exercise. I do hope to nail down and contribute a conventional-changelog-drupal package one day. In the meantime, I suggest you familiarize yourself with the default Angular change log preset.

Do leave comments giving me your thoughts. Hopefully, we can come up with a shared convention that makes sense for broader CMS web implementations. Again, this is a challenge, not for libraries, packages, distributions, or frameworks--all of which I think are covered well in the available online discussion on the topic--, but for the implementation of a web CMS project: the thing that is released, deployed, and edited by editors on production and contains content meant for a website visitor. It seems there are several layers of stakeholders. How do we communicate release changes to each in a way that makes sense to them?