Skip to content

The Documentation Release Process #2720

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 2 commits into from
Jun 29, 2013
Merged

The Documentation Release Process #2720

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
156eed7
Adding a section to outline the exact process the documentation team …
weaverryan Jun 12, 2013
f0d8675
[#2720] Tweaks thanks to @WouterJ
weaverryan Jun 12, 2013
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
4 changes: 4 additions & 0 deletions contributing/community/releases.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ release comes out every *six months*: one in *May* and one in *November*.
"rules" explained in this document must be strictly followed as of Symfony
2.4.

.. _contributing-release-development:

Development
-----------

Expand All @@ -29,6 +31,8 @@ During the development phase, any new feature can be reverted if it won't be
finished in time or if it won't be stable enough to be included in the current
final release.

.. _contributing-release-maintenance:

Maintenance
-----------

Expand Down
46 changes: 46 additions & 0 deletions contributing/documentation/overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,3 +184,49 @@ Read the dedicated :doc:`document <translations>`.
.. _`fork`: https://help.github.com/articles/fork-a-repo
.. _`pull requests`: https://help.github.com/articles/using-pull-requests
.. _`Documentation Build Errors`: http://symfony.com/doc/build_errors

Managing Releases
-----------------

Symfony has a very standardized release process, which you can read more
about in the :doc:`/contributing/community/releases` section.

To keep up with the release process, the documentation team makes several
changes to the documentation at various parts of the lifecycle.

When a Release reaches "end of maintenance"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Every release will eventually reach its "end of maintenance". For details,
see :ref`contributing-release-maintenance`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing colon


When a release reaches its end of maintenance, the following items are done.
For this example, suppose version 2.1 has just reached its end of maintenance:

* Changes and pull requests are no longer merged into to the branch (2.1),
except for security updates, which are merged until the release reaches
its "end of life".
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to add: except if the issues the PR fixes are milestoned with a specific version

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But if an issue is milestoned to, say, 2.0, then it either wouldn't be fixed (since we're passed maintenance), or it should only be fixed for branches that are still under maintenance. What do you think?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's take a milestoned issue: #2719 In 2.2, the routing system has changed and we use a lot of the deprecated methods in the documentation. Imagine the 2.2 branch was deprecated, isn't it completly wrong to not update that version but only update it in 2.3, as if the change was made in Symfony 2.3? We then have not working code in our documentation, just because we kept strict to the deprecation rule.

I think you can start deprecating things completely after all big things are fixed/documented. You can't deprecated the 2.1 version of the sf core if you know that it has some big bugs.

While we have a great doc team, we can't fully keep up with the core code (as that team is still much bigger). That's why I think we should not fully deprecate a doc branch, until all milestoned issues are fixed. Once a branch is fully deprecated, it needs to be fixed on the oldest maintained branch.

BTW, I recently removed the wrong milestones from issues, as some issues were milestoned but didn't really belong to a specific version,

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey Wouter!

I'm going to merge this in today, along with all of the other related PRs for versioning stuff and any other changes we need. Your situation here makes sense, but I'm not going to include it, at least for now. Of course, in reality, if we find some critical issue like this, we can bend our own rules. If a version has reached end-of-life, then it means it was released at least 1 year earlier, and we should certainly be able to get all of the critical fixes done in that time. Really, we should be able to get things updated during the "stabilization period.

Not including it here keeps the rule simple to read, though of course we can bend it if any rare item comes up.

Thanks!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok, I'm fine with merging this @weaverryan

(in case you are going to merge a lot of of PRs today, I'll update my open PRs within 3 hours to make them mergable)


* All branches still under maintenance (e.g. 2.2 and higher) are updated
to reflect that pull requests should start from the now-oldest maintained
version (e.g. 2.2).

* Remove all ``versionadded`` mentions - and any other notes related to features
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's use sphinx-speak here: "Remove all versionadded directives``

changing or being new - for the version (e.g. 2.1) from the master branch.
The result is that the next release (which is the first that comes entirely
*after* the end of maintenance of this branch), will have no mentions of
the old version (e.g. 2.1).

When a new Branch is created for a Release
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

During the :ref:`stabilization phase<contributing-release-development>`, a
new branch on the documentation is created. For example, if version 2.3 were
being stabilized, then a new 2.3 branch would be created for it. When this
happens, the following items are done:

* Change all version and master references to the correct version (e.g. 2.3).
For example, in installation chapters, we reference the version you should
use for installation. As an example, see the changes made in `PR #2688`_.

.. _`PR #2688`: https://github.com/symfony/symfony-docs/pull/2688