From 5ecb6422b6ca2b08ea51a32098c151fd07307f70 Mon Sep 17 00:00:00 2001 From: Changcheng Xiao Date: Tue, 15 Jan 2019 17:17:04 +0100 Subject: [PATCH] Move docs about project state to "config-project-config.txt" We have two documents, e.g. "config-project-config.txt" and "project-configuration.txt", containing doc for project configs. "config-project-config.txt" intends to document avaliable configs to the project through "project.config", "rules.pl" and "groups" file. "project.configuration" intends to document the configs avaliable through the UI. However, both of them are not complete, making it hard for users to learn how to config their projects. This commit and followup commits proposes to move docs about "Project Options" in "project-configuration.txt" to "config-project-config.txt" and then just referencing them from "project-configuration.txt". Hopefully, this could make it easier for users to understand Gerrit project configs. Change-Id: I0cf5013bd5260cf69cdb6e8ec51608cfc1d59d79 --- Documentation/config-project-config.txt | 36 ++++++++++++++++++++++++- Documentation/project-configuration.txt | 29 +------------------- 2 files changed, 36 insertions(+), 29 deletions(-) diff --git a/Documentation/config-project-config.txt b/Documentation/config-project-config.txt index 4456484bf3..a84077be00 100644 --- a/Documentation/config-project-config.txt +++ b/Documentation/config-project-config.txt @@ -96,7 +96,41 @@ The project section includes configuration of project settings. These are the keys: -- Description +[[description]]description:: ++ +A description for the project. + +[[state]]state: ++ +This setting defines the state of the project. A project can have the +following states: + +- `Active`: ++ +The project is active and users can see and modify the project according +to their access rights on the project. + +- `Read Only`: ++ +The project is read only and all modifying operations on it are +disabled. E.g. this means that pushing to this project fails for all +users even if they have push permissions assigned on it. ++ +Setting a project to this state is an easy way to temporary close a +project, as you can keep all write access rights in place and they will +become active again as soon as the project state is set back to +`Active`. ++ +This state also makes sense if a project was moved to another location. +In this case all new development should happen in the new project and +you want to prevent that somebody accidentally works on the old +project, while keeping the old project around for old references. + +- `Hidden`: ++ +The project is hidden and only visible to project owners. Other users +are not able to see the project even if they have read permissions +granted on the project. [[receive-section]] diff --git a/Documentation/project-configuration.txt b/Documentation/project-configuration.txt index f76b5e42d9..3ed3fddd64 100644 --- a/Documentation/project-configuration.txt +++ b/Documentation/project-configuration.txt @@ -143,35 +143,8 @@ to do a content merge when a path conflict occurs. [[project-state]] === State -This setting defines the state of the project. A project can have the -following states: +See details at link:config-project-config.html#project-section[project section]. -- `Active`: -+ -The project is active and users can see and modify the project according -to their access rights on the project. - -- `Read Only`: -+ -The project is read only and all modifying operations on it are -disabled. E.g. this means that pushing to this project fails for all -users even if they have push permissions assigned on it. -+ -Setting a project to this state is an easy way to temporary close a -project, as you can keep all write access rights in place and they will -become active again as soon as the project state is set back to -`Active`. -+ -This state also makes sense if a project was moved to another location. -In this case all new development should happen in the new project and -you want to prevent that somebody accidentally works on the old -project, while keeping the old project around for old references. - -- `Hidden`: -+ -The project is hidden and only visible to project owners. Other users -are not able to see the project even if they have read permissions -granted on the project. === Use target branch when determining new changes to open