Skip to content

Clarify how to write a commit message and CHANGELOGs #14830

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 15, 2021
Merged

Clarify how to write a commit message and CHANGELOGs #14830

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 68 additions & 18 deletions contributing/code/conventions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,10 @@ coding standards and conventions used in the core framework to make it more
consistent and predictable. You are encouraged to follow them in your own
code, but you don't need to.

Method Names
------------
.. _method-names:

Naming a Method
---------------

When an object has a "main" many relation with related "things"
(objects, parameters, ...), the method names are normalized:
Expand Down Expand Up @@ -77,19 +79,63 @@ must be used instead (where ``XXX`` is the name of the related thing):
``replaceXXX()``, on the other hand, cannot add new elements. If an unrecognized
key is passed to ``replaceXXX()`` it must throw an exception.

Writing a CHANGELOG Entry
-------------------------

When adding a new feature in a minor version or deprecating an existing
behavior, an entry to the relevant CHANGELOG(s) should be added.

New features and deprecations must be described in a file named
``CHANGELOG.md`` that should be at the root directory of the modified
Component, Bridge or Bundle.

The file must be written with the Markdown syntax and follow the following
conventions:

* The main title is always ``CHANGELOG``;

* Each entry must be added to a minor version section (like ``5.3``) as a list
element;

* No third level sections are allowed;

* Messages should follow the commit message conventions: should be short,
capitalize the line, do not end with a period, use an imperative verb to
start the line;

* New entries must be added on top of the list.

Here is a complete example for reference:

.. code-block:: markdown

CHANGELOG
=========

5.3
---

* Add `MagicConfig` that allows configuring things

.. note::

The main ``CHANGELOG-*`` files at the ``symfony/symfony`` root directory
are automatically generated when releases are prepared and should never be
modified manually.

.. _contributing-code-conventions-deprecations:

Deprecating Code
----------------

From time to time, some classes and/or methods are deprecated in the
framework; that happens when a feature implementation cannot be changed
because of backward compatibility issues, but we still want to propose a
"better" alternative. In that case, the old implementation can be **deprecated**.
From time to time, some classes and/or methods are deprecated in the framework;
that happens when a feature implementation cannot be changed because of
backward compatibility issues, but we still want to propose a "better"
alternative. In that case, the old implementation can be **deprecated**.

Deprecations must only be introduced on the next minor version of the impacted
component (or bundle, or bridge, or contract).
They can exceptionally be introduced on previous supported versions if they are critical.
component (or bundle, or bridge, or contract). They can exceptionally be
introduced on previous supported versions if they are critical.

A new class (or interface, or trait) cannot be introduced as deprecated, or
contain deprecated methods.
Expand Down Expand Up @@ -144,26 +190,28 @@ after the use declarations, like in this example from

The deprecation must be added to the ``CHANGELOG.md`` file of the impacted component::

4.4.0
-----
4.4
---

* Deprecated the `Deprecated` class, use `Replacement` instead.
* Deprecate the `Deprecated` class, use `Replacement` instead

It must also be added to the ``UPGRADE.md`` file of the targeted minor version
(``UPGRADE-4.4.md`` in our example)::

DependencyInjection
-------------------

* Deprecated the `Deprecated` class, use `Replacement` instead.
* Deprecate the `Deprecated` class, use `Replacement` instead

Finally, its consequences must be added to the ``UPGRADE.md`` file of the next major version
(``UPGRADE-5.0.md`` in our example)::
(``UPGRADE-5.0.md`` in our example):

.. code-block:: markdown

DependencyInjection
-------------------

* Removed the `Deprecated` class, use `Replacement` instead.
* Remove the `Deprecated` class, use `Replacement` instead

All these tasks are mandatory and must be done in the same pull request.

Expand All @@ -174,12 +222,14 @@ Removing deprecated code can only be done once every 2 years, on the next major
impacted component (``master`` branch).

When removing deprecated code, the consequences of the deprecation must be added to the ``CHANGELOG.md`` file
of the impacted component::
of the impacted component:

.. code-block:: markdown

5.0.0
-----
5.0
---

* Removed the `Deprecated` class, use `Replacement` instead.
* Remove the `Deprecated` class, use `Replacement` instead

This task is mandatory and must be done in the same pull request.

Expand Down
22 changes: 12 additions & 10 deletions contributing/code/pull_requests.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -224,7 +224,18 @@ in mind the following:
* Never fix coding standards in some existing code as it makes the code review
more difficult;

* Write good commit messages (see the tip below).
* Write good commit messages: Start by a short subject line (the first line),
followed by a blank line and a more detailed description.

The subject line should start with the Component, Bridge or Bundle you are
working on in square brackets (``[DependencyInjection]``,
``[FrameworkBundle]``, ...).

Then, capitalize the sentence, do not end with a period, and use an
imperative verb to start.

Here is a full example of a subject line: ``[MagicBundle] Add `MagicConfig`
that allows configuring things``.

.. tip::

Expand All @@ -235,15 +246,6 @@ in mind the following:
A status is posted below the pull request description with a summary
of any problems it detects or any `Travis-CI`_ build failures.

.. tip::

A good commit message is composed of a summary (the first line),
optionally followed by a blank line and a more detailed description. The
summary should start with the Component you are working on in square
brackets (``[DependencyInjection]``, ``[FrameworkBundle]``, ...). Use a
verb (``fixed ...``, ``added ...``, ...) to start the summary and don't
add a period at the end.

.. _prepare-your-patch-for-submission:

Prepare your Pull Request for Submission
Expand Down