Browse files

docs(contributing): clarifies release periods and branches for PRs

  • Loading branch information...
mrclay committed Mar 16, 2016
1 parent c2b2f7f commit b82d1592d0b584c4e90a6d863eaa7c9803623b5d
Showing with 29 additions and 24 deletions.
  1. +5 −5 docs/appendix/releases.rst
  2. +24 −19 docs/contribute/code.rst
@@ -11,9 +11,9 @@ Follow the blog to `stay up to date on the latest releases`__.
Patch/Bugfix Releases (1.9.x)
Patch/Bugfix Releases (2.1.x)
Every few weeks.
Every two weeks.
Bugfix releases are made regularly to make sure Elgg stays stable, secure, and bug-free.
The higher the third digit, the more tested and stable the release is.
@@ -22,9 +22,9 @@ Since bugfix release focus on fixing bugs and not making major changes,
themes and plugins should work from bugfix release to bugfix release.
Minor/Feature Releases (1.x.0)
Minor/Feature Releases (2.x.0)
Every few months.
Every three months.
Whenever we introduce new features, we'll bump the middle version number.
These releases aren't as mature as bugfix release, but are considered stable and useable.
@@ -37,7 +37,7 @@ However, plugins might need to be updated to make use of the new features.
Major/Breaking Releases (x.0.0)
Every few years.
Every year.
Inevitably, improving Elgg requires breaking changes and a new major release is made.
These releases are opportunities for the core team to make strategic, breaking changes to the underlying platform.
@@ -57,18 +57,21 @@ Feature PRs:
Choosing a branch to submit to
The following table assumes the latest stable release is 1.9.
============== ====================================
Type of change Branch to submit against
============== ====================================
Security fix 1.8 (Email first!)
Bug fix 1.9
Deprecation 1.x
Minor feature 1.x
Major feature master
Breaking master
============== ====================================
The following table assumes the latest stable release is 2.1.
============================== ============================================
Type of change Branch to submit against
============================== ============================================
Security fix Don't! Email for guidance.
Bug fix 1.12 (or 2.1 if the 1.12 fix is too complex)
Performance 2.x
Deprecation 2.x
Minor feature 2.x
Major feature master
Has any breaking change master
============================== ============================================
If you're not sure which branch to submit against, just ask!
The difference between minor and major feature is subjective and up to the core team.
@@ -94,7 +97,7 @@ follow these steps:
2. In parenthesis, add the ``component``, a short string which describes the subsystem being changed.
Some examples: "views", "i18n", "seo", "a11y", "cache", "db", "session", "router", "<plugin_name>".
Some examples: ``views``, ``i18n``, ``seo``, ``a11y``, ``cache``, ``db``, ``session``, ``router``, ``<plugin_name>``.
3. Add a colon, a space, and a brief ``summary`` of the changes, which will appear in the changelog.
@@ -167,14 +170,16 @@ To edit just the last commit:
1. Amend the commit: ``git commit --amend`` (git opens the message in a text editor).
2. Change the message and save/exit the editor.
3. Force push your branch: ``git push -f your_remote your_branch`` (your PR with be updated).
4. Rename the PR title to match
Otherwise you may need to perform an interactive rebase:
1. Rebase the last N commits: ``git rebase -i HEAD~N`` where N is a number.
(Git will open the git-rebase-todo file for editing)
(Git will open the ``git-rebase-todo`` file for editing)
2. For the commits that need to change, change ``pick`` to ``r`` (for reword) and save/exit the editor.
3. Change the commit message(s), save/exit the editor (git will present a file for each commit that needs rewording).
4. ``git push -f your_remote your_branch`` to force push the branch (updating your PR).
5. Rename the PR title to match
.. _contribute/code#testing:
@@ -325,22 +330,22 @@ Avoid double-negatives. Prefer ``$enable = true`` to ``$disable = false``.
Interface names
Use the pattern `Elgg\{Namespace}\{Name}`.
Use the pattern ``Elgg\{Namespace}\{Name}``.
Do not include an `I` prefix or an `Interface` suffix.
Do not include an ``I`` prefix or an ``Interface`` suffix.
We do not include any prefix or suffix so that we're encouraged to:
* name implementation classes more descriptively (the "default" name is taken).
* type-hint on interfaces, because that is the shortest, easiest thing to do.
Name implementations like `Elgg\{Namespace}\{Interface}\{Implementation}`.
Name implementations like ``Elgg\{Namespace}\{Interface}\{Implementation}``.
Where possible, have functions/methods return a single type.
Use empty values such as array(), "", or 0 to indicate no results.
Use empty values such as ``array()``, ``""``, or ``0`` to indicate no results.
Be careful where valid return values (like ``"0"``) could be interpreted as empty.
@@ -556,7 +561,7 @@ Good:
Property declarations
These should be spaced like so: `property: value;`
These should be spaced like so: ``property: value;``

0 comments on commit b82d159

Please sign in to comment.