Trim and focus for GitLab content

Author: ben

en/book/04-git-server/chapter4.asc

@@ -609,19 +609,18 @@ GitLab is a fully open-source project (the project page can be found at http://w
 There are several options for obtaining and using GitLab:
 
 1. The Community Edition is the basic product, and is offered free of charge.
-   You install the software on your machine, and you're in charge of configuring and updating it.
-   No money changes hands, the software is entirely open-source.
-2. The Enterprise Edition extends the Community Edition with some extra features, and is available under a subscription plan.
+   You install the software on your machine, and you're responsible for configuring and updating it.
+2. The Enterprise Edition extends the Community Edition with some extra features, and is available through a subscription plan.
    Your subscription fees pay for installation and configuration support, ongoing technical support, and continued GitLab development.
 3. GitLab Cloud is an installation of the Community Edition running on GitLab's servers.
    There's no charge for the service, and very few limits on how you use it.
-   This is a great way to try GitLab from a user's perspective before expending effort configuring your own server.
+   This is a great way to take GitLab for a spin before expending effort configuring your own server.
 
 
 ==== Installation
 
 GitLab is a database-backed web application, so its installation is a bit more involved than some other git servers.
-Fortunately, it's also very well-documented and supported.
+Fortunately, this process is very well-documented and supported.
 
 There are a few methods you can pursue to install GitLab.
 To get something up and running quickly, you can download a virtual machine image or a one-click installer from https://bitnami.com/stack/gitlab[], and tweak the configuration to match your particular environment.
@@ -639,7 +638,7 @@ There's also ``unofficial'' guidance on getting GitLab running with non-standard
 ==== Administration
 
 GitLab's administration interface is accessed over the web.
-Simply point your browser to the hostname or IP address of the machine where GitLab is installed, and log in as an admin user.
+Simply point your browser to the hostname or IP address where GitLab is installed, and log in as an admin user.
 The default username is `[email protected]`, and the default password is `5iveL!fe` (which you will be prompted to change as soon as you enter it).
 Once logged in, click the ``Admin area'' icon in the menu at the top right.
 
@@ -650,10 +649,9 @@ image::images/gitlab-menu.png[The ``Admin area'' item in the GitLab menu.]
 ===== Users
 
 Users in GitLab are accounts that correspond to people.
-User accounts don't have a lot of complexity.
-Mainly it's a collection of personal information attached to login data.
+User accounts don't have a lot of complexity; mainly it's a collection of personal information attached to login data.
 Each user account comes with a *namespace*, which is a logical grouping of projects that belong to that user.
-If the user +jane+ had a project named +project+, that project's url would be http://hostname.tld/jane/project[].
+If the user +jane+ had a project named +project+, that project's url would be http://server/jane/project[].
 
 [[gitlab_users]]
 .The GitLab user administration screen.
@@ -669,14 +667,14 @@ This is obviously a much more permanent and destructive action, and its uses are
 ===== Groups
 
 A GitLab group is an assemblage of projects, along with data about how users can access those projects.
-Each group is a project namespace (the same way that users are), so if the group +training+ had a project +materials+, its url would be http://hostname.tld/training/materials[].
+Each group has a project namespace (the same way that users do), so if the group +training+ has a project +materials+, its url would be http://server/training/materials[].
 
 [[gitlab_groups]]
 .The GitLab group administration screen.
 image::images/gitlab-groups.png[The GitLab group administration screen.]
 
 Each group is associated with a number of users, each of which has a level of permissions for the group's projects and the group itself.
-These range from ``Guest'' (issues and chat only) to ``Owner'' (full control of the group and its projects).
+These range from ``Guest'' (issues and chat only) to ``Owner'' (full control of the group, its members, and its projects).
 The types of permissions are too numerous to list here, but GitLab has a helpful link on the administration screen.
 
 ===== Projects
@@ -685,70 +683,58 @@ A GitLab project roughly corresponds to a single git repository.
 Every project belongs to a single namespace, either a user or a group.
 If the project belongs to a user, the owner of the project has direct control over who has access to the project; if the project belongs to a group, the group's user-level permissions will also take effect.
 
-Every project has a visibility level, which controls who has read access to that project's pages and repository.
+Every project also has a visibility level, which controls who has read access to that project's pages and repository.
 If a project is _Private_, the project's owner must explicitly grant access to specific users.
 An _Internal_ project is visible to any logged-in user, and a _Public_ project is visible to anyone.
 Note that this controls both git "fetch" access as well as access to the web UI for that project.
 
-Projects can also have labels, which can help organize projects across namespaces.
-The projects dashboard page can filter the displayed repositories by one or more labels.
-This is helpful if you have a large number of projects in different groups, but that relate in some way.
+===== Hooks
 
-===== Other Tools
-
-GitLab includes support for *Hooks*, both at a project or system level.
+GitLab includes support for hooks, both at a project or system level.
 For either of these, the GitLab server will perform an HTTP POST with some descriptive JSON whenever relevant events occur.
 This is a great way to connect your git repositories and GitLab instance to the rest of your development automation, such as CI servers, chat rooms, or deployment tools.
 
-The *Message* feature is useful to broadcast information about the system to all users.
-A maximum of one message is visible at any given time, and every message has a window of time during which it is visible to any user (including anonymous ones).
-
-[[gitlab_message]]
-.How a message is displayed.
-image::images/gitlab-broadcast.png[How a message is displayed.]
-
-This is typically used for system status information (_"The server will be undergoing maintenance…"_), but administrative users have full control over the content and color scheme.
-
-==== Basic Operation
+==== Basic Usage
 
 The first thing you'll want to do with GitLab is create a new project.
 This is accomplished by clicking the ``+'' icon on the toolbar.
 You'll be asked for the project's name, which namespace it should belong to, and what its visibility level should be.
 Most of what you specify here isn't permanent, and can be re-adjusted later through the settings interface.
 Click ``Create Project'', and you're done.
 
-Once the project is created, you'll probably want to connect it with a local Git repository.
+Once the project exists, you'll probably want to connect it with a local Git repository.
 Each project is accessible over HTTPS or SSH, either of which can be used to configure a Git remote.
 The URLs are visible at the top of the project's home page.
 For an existing local repository, this command will create a remote named `gitlab` to the hosted location:
 
-    git remote add gitlab <url>
+    git remote add gitlab https://server/namespace/project.git
 
 If you don't have a local copy of the repository, you can simply do this:
 
-    git clone <url>
-
+    git clone https://server/namespace/project.git
 
-The web UI provides access to many useful views of the repository itself.
+The web UI provides access to several useful views of the repository itself.
 Each project's home page shows recent activity, and links along the top will lead you to views of the project's files and commit log.
 
 ==== Working Together
 
-The most basic way of working together on a GitLab project is by giving another user direct push access to the git repository.
-You can add another user to a project by going to the ``Members'' section of that project's settings, and associating the new user with an access level (the different access levels are discussed a bit in <<_gitlab_groups_section>>).
+The simplest way of working together on a GitLab project is by giving another user direct push access to the git repository.
+You can add a user to a project by going to the ``Members'' section of that project's settings, and associating the new user with an access level (the different access levels are discussed a bit in <<_gitlab_groups_section>>).
 By giving a user an access level of ``Developer'' or above, that user can push commits and branches directly to the repository with impunity.
 
-Another, more isolated way of collaboration is by using merge requests.
+Another, more decoupled way of collaboration is by using merge requests.
 This feature enables any user that can see a project to contribute to it in a controlled way.
 Users with direct access can simply create a branch, push commits to it, and open a merge request from their branch back into `master` or any other branch.
 Users who don't have push permissions for a repository can ``fork'' it (create their own copy), push commits to _that_ copy, and open a merge request from their fork back to the main project.
 This model allows the owner to be in full control of what goes into the repository and when, while allowing contributions from untrusted users.
 
 Merge requests and issues are the main units of long-lived discussion in GitLab.
-Each merge request allows a line-by-line discussion of the proposed change, as well as a general overall discussion thread.
+Each merge request allows a line-by-line discussion of the proposed change (which supports a lightweight kind of code review), as well as a general overall discussion thread.
 Both can be assigned to users, or organized into milestones.
 
-* The Wall
+This section has focused mainly on the Git-related parts of GitLab, but it's a fairly mature system, and provides many other features that can help your team work together.
+These include project wikis, discussion ``walls'', and system maintenance tools.
+One benefit to GitLab is that, once the server is set up and running, you'll rarely need to tweak a configuration file or access the server via SSH; most administration and general usage can be accomplished through the in-browser interface.
 
 === Gerrit