opendev/gerrit
Code Issues Proposed changes

Merge changes from topic "doc-restructuring"

Browse Source 
* changes:
  Extract dev processes from dev-contributing.txt into a separate page
  Make Contributor License Agreement a separate documentation page
  dev-community.txt: Add anchors for all sections
  dev-community.txt: Make 'How to contribute' a separate section
  dev-community.txt: Move 'System Design' into 'Project Information' section
  Drop outdated documentation about i18n support
  Move 'Project Information' up to the community index page
  dev-design.txt: Fix link to release versions
  dev-design.txt: Fix link to change review
  Drop 'Caveats' section from dev design
  Drop 'Testing Plan' section from dev design
  Community index page: Drop entries that are part of dev setup
  Add a separate documentation page for community-related contents
This commit is contained in:
David Pursehouse
2019-04-24 00:09:14 +00:00
committed by Gerrit Code Review
parent 17fe02418e c500df0747
commit 6524ae6f25
7 changed files with 169 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
Documentation/dev-cla.txt Normal file
View File

@@ -0,0 +1,26 @@
= Gerrit Code Review - Contributor License Agreement
In order to link::dev-community.html#how-to-contribute[contribute] to
Gerrit a Contributor License Agreement must be completed before
contributions are accepted. To view and accept the agreements do the
following:
. Click 'Sign In' at the top right corner of
https://gerrit-review.googlesource.com/
. Sign In with your Google account
. After signing in, go to the
link:https://gerrit-review.googlesource.com/#/settings/agreements[Agreements]
tab on the settings page
. Click on 'New Contributor Agreement' and follow the instructions
For reference, the actual agreements are linked below
* link:https://cla.developers.google.com/about/android-individual[Individual Agreement]
* link:https://source.android.com/source/cla-corporate.pdf[Corporate Agreement]
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------

47
Documentation/dev-community.txt Normal file
View File

@@ -0,0 +1,47 @@
= Gerrit Community
[[project-information]]
== Project Information
Gerrit is developed as a self-hosting open source project:
* link:https://www.gerritcodereview.com/[Project Homepage]
* link:https://www.gerritcodereview.com/releases-readme.html[Release Versions]
* link:https://gerrit.googlesource.com/gerrit[Source]
* link:https://bugs.chromium.org/p/gerrit/issues/list[Issue Tracking]
* link:https://gerrit-review.googlesource.com/q/status:open+project:gerrit[Change Review]
* link:dev-design.html[System Design]
* Processes
** link:dev-contributing.html[Contribution Process]
** link:dev-processes.html#dev-in-stable-branches[Development in stable branches]
** link:dev-processes.html#backporting[Backporting to stable branches]
** link:dev-processes.html#upgrading-libraries[Upgrading Libraries]
** link:dev-processes.html#deprecating-features[Deprecating features]
[[how-to-contribute]]
== How to contribute?
* link:dev-cla.html[Contributor License Agreement]
* link:dev-contributing.html[Contributing to Gerrit]
* link:dev-readme.html[Developer Setup]
[[plugin-development]]
== Plugin Development
* link:dev-plugins.html[Developing Plugins]
* link:dev-build-plugins.html[Building Gerrit plugins]
* link:js-api.html[JavaScript Plugin API]
* link:config-validation.html[Validation Interfaces]
* link:dev-stars.html[Starring Changes]
* link:quota.html[Quota Enforcement]
[[maintainer]]
== Maintainer
* link:dev-release.html[Making a Gerrit Release]
* link:dev-release-subproject.html[Making a Release of a Gerrit Subproject]
* link:dev-release-jgit.html[Making a Release of JGit]
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------

107
Documentation/dev-contributing.txt
View File

@@ -3,24 +3,8 @@
== Introduction == Introduction
Gerrit is developed as a Gerrit is developed as a
link:https://gerrit-review.googlesource.com/[self-hosting open source project] link:https://gerrit-review.googlesource.com/[self-hosting open source project]
and very much welcomes contributions from anyone with a contributor's and very much welcomes contributions from anyone with a
agreement on file with the project. link:dev-cla.html[contributor's agreement] on file with the project.
== Contributor License Agreement
A Contributor License Agreement must be completed before contributions
are accepted. To view and accept the agreements do the following:
* Click 'Sign In' at the top right corner of https://gerrit-review.googlesource.com/
* Sign In with your Google account
* After signing in, go to the
link:https://gerrit-review.googlesource.com/#/settings/agreements[Agreements]
tab on the settings page
* Click 'New Contributor Agreement' and follow the instructions
For reference, the actual agreements are linked below
* link:https://cla.developers.google.com/about/android-individual[Individual Agreement]
* link:https://source.android.com/source/cla-corporate.pdf[Corporate Agreement]
== Code Review == Code Review
As Gerrit is a code review tool, naturally contributions will As Gerrit is a code review tool, naturally contributions will
@@ -318,49 +302,7 @@ especially if changing one without the other will break something!
and it also makes `git revert` more useful. and it also makes `git revert` more useful.
* Use topics to link your separate changes together. * Use topics to link your separate changes together.
[[process]] == Finding starter projects to work on
== Process
[[dev-in-stable-branches]]
=== Development in stable branches
As their name suggests stable branches are intended to be stable. This means that generally
only bug-fixes should be done on stable branches, however this is not strictly enforced and
exceptions may apply:
* When a stable branch is initially created to prepare a new release the Gerrit community
discusses on the mailing list if there are pending features which should still make it into the
release. Those features are blocking the release and should be implemented on the stable
branch before the first release candidate is created.
* To stabilize the code before doing a major release several release candidates are created. Once
the first release candidate was done no more features should be accepted on the stable branch.
If more features are found to be required they should be discussed with the Gerrit maintainers
and should only be allowed if the risk of breaking things is considered to be low.
* Once a major release is done only bug-fixes and documentation updates should be done on the
stable branch. These updates will be included in the next minor release.
* For minor releases new features are only acceptable if they are important to the Gerrit
community, if they are backwards compatible and the risk of breaking things is low and if there
are no objections from the Gerrit community.
* In cases of doubt it's the responsibility of the release maintainer to evaluate the risk of new
features and make a decision based on these rules and opinions from the Gerrit community.
* The older a stable branch is the more stable it should be. This means old stable branches
should only receive bug-fixes that are either important or low risk. Security fixes, including
security updates for third party dependencies, are always considered as important and hence can
always be done on stable branches.
=== Backporting to stable branches
From time to time bug fix releases are made for existing stable branches.
Developers concerned with stable branches are encouraged to backport or push fixes to these
branches, even if no new release is planned. Backporting features is only possible in compliance
with the rules link:#dev-in-stable-branches[above].
Fixes that are known to be needed for a particular release should be pushed for review on that
release's stable branch. They will then be included into the master branch when the stable branch
is merged back.
=== Finding starter projects to work on
We have created a We have created a
link:https://bugs.chromium.org/p/gerrit/issues/list?can=2&q=label%3AStarterProject[StarterProject] link:https://bugs.chromium.org/p/gerrit/issues/list?can=2&q=label%3AStarterProject[StarterProject]
@@ -368,49 +310,6 @@ category in the issue tracker and try to assign easy hack projects to it. If in
doubt, do not hesitate to ask on the developer doubt, do not hesitate to ask on the developer
link:https://groups.google.com/forum/#!forum/repo-discuss[mailing list]. link:https://groups.google.com/forum/#!forum/repo-discuss[mailing list].
=== Upgrading Libraries
Gerrit's library dependencies should only be upgraded if the new version contains
something we need in Gerrit. This includes new features, API changes as well as bug
or security fixes.
An exception to this rule is that right after a new Gerrit release was branched
off, all libraries should be upgraded to the latest version to prevent Gerrit
from falling behind. Doing those upgrades should conclude at the latest two
months after the branch was cut. This should happen on the master branch to ensure
that they are vetted long enough before they go into a release and we can be sure
that the update doesn't introduce a regression.
[[deprecating-features]]
=== Deprecating features
Gerrit should be as stable as possible and we aim to add only features that last.
However, sometimes we are required to deprecate and remove features to be able
to move forward with the project and keep the code-base clean. The following process
should serve as a guideline on how to deprecate functionality in Gerrit. Its purpose
is that we have a structured process for deprecation that users, administrators and
developers can agree and rely on.
General process:
* Make sure that the feature (e.g. a field on the API) is not needed anymore or blocks
further development or improvement. If in doubt, consult the mailing list.
* If you can provide a schema migration that moves users to a comparable feature, do
so and stop here.
* Mark the feature as deprecated in the documentation and release notes.
* If possible, mark the feature deprecated in any user-visible interface. For example,
if you are deprecating a Git push option, add a message to the Git response if
the user provided the option informing them about deprecation.
* Annotate the code with `@Deprecated` and `@RemoveAfter(x.xx)` if applicable.
Alternatively, use `// DEPRECATED, remove after x.xx` (where x.xx is the version
number that has to be branched off before removing the feature)
* Gate the feature behind a config that is off by default (forcing admins to turn
the deprecated feature on explicitly).
* After the next release was branched off, remove any code that backed the feature.
You can optionally consult the mailing list to ask if there are users of the feature you
wish to deprecate. If there are no major users, you can remove the feature without
following this process and without the grace period of one release.
GERRIT GERRIT
------ ------
Part of link:index.html[Gerrit Code Review] Part of link:index.html[Gerrit Code Review]

36
Documentation/dev-design.txt
View File

@@ -178,17 +178,6 @@ has been migrated out of the database and into the git
repositories for each project. repositories for each project.
== Project Information
Gerrit is developed as a self-hosting open source project:
* link:https://www.gerritcodereview.com/[Project Homepage]
* link:https://www.gerritcodereview.com/download/index.html[Release Versions]
* link:https://gerrit.googlesource.com/gerrit[Source]
* link:https://bugs.chromium.org/p/gerrit/issues/list[Issue Tracking]
* link:https://review.source.android.com/[Change Review]
== Internationalization and Localization == Internationalization and Localization
As a source code review system for open source projects, where the As a source code review system for open source projects, where the
@@ -204,8 +193,6 @@ Gerrit code base. Some portions of the code have tried to take
RTL into consideration, while others probably need to be modified RTL into consideration, while others probably need to be modified
before translating the UI to an RTL language. before translating the UI to an RTL language.
* link:i18n-readme.html[Gerrit's i18n Support]
== Accessibility Considerations == Accessibility Considerations
@@ -640,29 +627,6 @@ logs may be mined for usage information. This is outside of the
scope of Gerrit. scope of Gerrit.
== Testing Plan
Gerrit is currently manually tested through its web UI.
JGit has a fairly extensive automated unit test suite. Most new
changes to JGit are rejected unless corresponding automated unit
tests are included.
== Caveats
Rietveld can't be used as it does not provide the "submit over the
web" feature that Gerrit provides for Git.
Gitosis can't be used as it does not provide any code review
features, but it does provide basic access controls.
Email based code review does not scale to a project as large and
complex as Android. Most contributors at least need some sort of
dashboard to keep track of any pending reviews, and some way to
correlate updated revisions back to the comments written on prior
revisions of the same logical change.
GERRIT GERRIT
------ ------
Part of link:index.html[Gerrit Code Review] Part of link:index.html[Gerrit Code Review]

92
Documentation/dev-processes.txt Normal file
View File

@@ -0,0 +1,92 @@
= Gerrit Code Review - Development Processes
[[dev-in-stable-branches]]
== Development in stable branches
As their name suggests stable branches are intended to be stable. This means that generally
only bug-fixes should be done on stable branches, however this is not strictly enforced and
exceptions may apply:
* When a stable branch is initially created to prepare a new release the Gerrit community
discusses on the mailing list if there are pending features which should still make it into the
release. Those features are blocking the release and should be implemented on the stable
branch before the first release candidate is created.
* To stabilize the code before doing a major release several release candidates are created. Once
the first release candidate was done no more features should be accepted on the stable branch.
If more features are found to be required they should be discussed with the Gerrit maintainers
and should only be allowed if the risk of breaking things is considered to be low.
* Once a major release is done only bug-fixes and documentation updates should be done on the
stable branch. These updates will be included in the next minor release.
* For minor releases new features are only acceptable if they are important to the Gerrit
community, if they are backwards compatible and the risk of breaking things is low and if there
are no objections from the Gerrit community.
* In cases of doubt it's the responsibility of the release maintainer to evaluate the risk of new
features and make a decision based on these rules and opinions from the Gerrit community.
* The older a stable branch is the more stable it should be. This means old stable branches
should only receive bug-fixes that are either important or low risk. Security fixes, including
security updates for third party dependencies, are always considered as important and hence can
always be done on stable branches.
[[backporting]]
== Backporting to stable branches
From time to time bug fix releases are made for existing stable branches.
Developers concerned with stable branches are encouraged to backport or push fixes to these
branches, even if no new release is planned. Backporting features is only possible in compliance
with the rules link:#dev-in-stable-branches[above].
Fixes that are known to be needed for a particular release should be pushed for review on that
release's stable branch. They will then be included into the master branch when the stable branch
is merged back.
[[upgrading-libraries]]
== Upgrading Libraries
Gerrit's library dependencies should only be upgraded if the new version contains
something we need in Gerrit. This includes new features, API changes as well as bug
or security fixes.
An exception to this rule is that right after a new Gerrit release was branched
off, all libraries should be upgraded to the latest version to prevent Gerrit
from falling behind. Doing those upgrades should conclude at the latest two
months after the branch was cut. This should happen on the master branch to ensure
that they are vetted long enough before they go into a release and we can be sure
that the update doesn't introduce a regression.
[[deprecating-features]]
== Deprecating features
Gerrit should be as stable as possible and we aim to add only features that last.
However, sometimes we are required to deprecate and remove features to be able
to move forward with the project and keep the code-base clean. The following process
should serve as a guideline on how to deprecate functionality in Gerrit. Its purpose
is that we have a structured process for deprecation that users, administrators and
developers can agree and rely on.
General process:
* Make sure that the feature (e.g. a field on the API) is not needed anymore or blocks
further development or improvement. If in doubt, consult the mailing list.
* If you can provide a schema migration that moves users to a comparable feature, do
so and stop here.
* Mark the feature as deprecated in the documentation and release notes.
* If possible, mark the feature deprecated in any user-visible interface. For example,
if you are deprecating a Git push option, add a message to the Git response if
the user provided the option informing them about deprecation.
* Annotate the code with `@Deprecated` and `@RemoveAfter(x.xx)` if applicable.
Alternatively, use `// DEPRECATED, remove after x.xx` (where x.xx is the version
number that has to be branched off before removing the feature)
* Gate the feature behind a config that is off by default (forcing admins to turn
the deprecated feature on explicitly).
* After the next release was branched off, remove any code that backed the feature.
You can optionally consult the mailing list to ask if there are users of the feature you
wish to deprecate. If there are no major users, you can remove the feature without
following this process and without the grace period of one release.
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------

24
Documentation/i18n-readme.txt
View File

@@ -1,24 +0,0 @@
= Gerrit Code Review - i18n
Aside from actually writing translations, there are some issues with
the way the code produces output. Most of the UI should support
right-to-left (RTL) languages.
== Labels
Labels and their values are defined in project.config by the Gerrit
administrator or project owners. Only a single translation of these
strings is supported.
== /Gerrit Gerrit.html
* The title of the host page is not translated.
* The <noscript> tag is not translated.
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------

23
Documentation/index.txt
View File

@@ -9,6 +9,7 @@
. link:intro-quick.html[Product Overview] . link:intro-quick.html[Product Overview]
. link:intro-how-gerrit-works.html[How Gerrit Works] . link:intro-how-gerrit-works.html[How Gerrit Works]
. link:intro-gerrit-walkthrough.html[Basic Gerrit Walkthrough] . link:intro-gerrit-walkthrough.html[Basic Gerrit Walkthrough]
. link:dev-community.html[Gerrit Community]
== Guides == Guides
. link:intro-user.html[User Guide] . link:intro-user.html[User Guide]
@@ -72,28 +73,6 @@
. link:config-accounts.html[Accounts on NoteDb] . link:config-accounts.html[Accounts on NoteDb]
. link:config-groups.html[Groups on NoteDb] . link:config-groups.html[Groups on NoteDb]
== Developer
. Getting Started
.. link:dev-readme.html[Developer Setup]
.. link:dev-bazel.html[Building with Bazel]
.. link:dev-eclipse.html[Eclipse Setup]
.. link:dev-intellij.html[IntelliJ Setup]
.. link:dev-contributing.html[Contributing to Gerrit]
. Plugin Development
.. link:dev-plugins.html[Developing Plugins]
.. link:dev-build-plugins.html[Building Gerrit plugins]
.. link:js-api.html[JavaScript Plugin API]
.. link:config-validation.html[Validation Interfaces]
.. link:dev-stars.html[Starring Changes]
.. link:quota.html[Quota Enforcement]
. link:dev-design.html[System Design]
. link:i18n-readme.html[i18n Support]
== Maintainer
. link:dev-release.html[Making a Gerrit Release]
. link:dev-release-subproject.html[Making a Release of a Gerrit Subproject]
. link:dev-release-jgit.html[Making a Release of JGit]
== Concepts == Concepts
. link:config-labels.html[Review Labels] . link:config-labels.html[Review Labels]
. link:access-control.html[Access Controls] . link:access-control.html[Access Controls]