SONAR-10676 Add documentation for team onboarding on SonarCloud "Members" page (#251)

10 files changed, 126 insertions, 12 deletions

diff --git a/server/sonar-docs/gatsby-node.js b/server/sonar-docs/gatsby-node.js
index 7bee8372b44..c9cd2fd4837 100644
--- a/server/sonar-docs/gatsby-node.js
+++ b/server/sonar-docs/gatsby-node.js
@@ -41,6 +41,9 @@ exports.createPages = ({ graphql, boundActionCreators }) => {
         allMarkdownRemark {
           edges {
             node {
+              frontmatter {
+                scope
+              }
               fields {
                 slug
               }
@@ -50,14 +53,16 @@ exports.createPages = ({ graphql, boundActionCreators }) => {
       }
     `).then(result => {
       result.data.allMarkdownRemark.edges.forEach(({ node }) => {
-        createPage({
-          path: node.fields.slug,
-          component: path.resolve('./src/templates/page.js'),
-          context: {
-            // Data passed to context is available in page queries as GraphQL variables.
-            slug: node.fields.slug
-          }
-        });
+        if (node.frontmatter.scope !== 'sonarcloud') {
+          createPage({
+            path: node.fields.slug,
+            component: path.resolve('./src/templates/page.js'),
+            context: {
+              // Data passed to context is available in page queries as GraphQL variables.
+              slug: node.fields.slug
+            }
+          });
+        }
       });
       resolve();
     });
diff --git a/server/sonar-docs/src/EmbedDocsSuggestions.json b/server/sonar-docs/src/EmbedDocsSuggestions.json
index 91be7e4892e..fce00fdf549 100644
--- a/server/sonar-docs/src/EmbedDocsSuggestions.json
+++ b/server/sonar-docs/src/EmbedDocsSuggestions.json
@@ -33,6 +33,20 @@
     }
   ],
   "marketplace": [],
+  "organization_members": [
+    {
+      "link": "/documentation/organizations/manage-team",
+      "text": "Manage a Team",
+      "scope": "sonarcloud"
+    }
+  ],
+  "organization_projects": [
+    {
+      "link": "/documentation/organizations/index",
+      "text": "Organizations",
+      "scope": "sonarcloud"
+    }
+  ],
   "overview": [
     {
       "link": "/documentation/fixing-the-water-leak",
diff --git a/server/sonar-docs/src/pages/branches/branches-faq.md b/server/sonar-docs/src/pages/branches/branches-faq.md
index 63bc9cab628..58bacdcf22e 100644
--- a/server/sonar-docs/src/pages/branches/branches-faq.md
+++ b/server/sonar-docs/src/pages/branches/branches-faq.md
@@ -2,8 +2,12 @@
 title: Frequently Asked Branches Questions
 ---
 
+<!-- sonarqube -->
+
 _Branch analysis is available as part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)_
 
+<!-- /sonarqube -->
+
 **Q:** How long are branches retained?  
 **A:** Long-lived branches are retained until you delete them manually (**Administration > Branches**).
 Short-lived branches are deleted automatically after 30 days with no analysis.
diff --git a/server/sonar-docs/src/pages/branches/index.md b/server/sonar-docs/src/pages/branches/index.md
index 29f168cff2f..67de486046c 100644
--- a/server/sonar-docs/src/pages/branches/index.md
+++ b/server/sonar-docs/src/pages/branches/index.md
@@ -2,8 +2,12 @@
 title: Branches
 ---
 
+<!-- sonarqube -->
+
 _Branch analysis is available as part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)_
 
+<!-- /sonarqube -->
+
 Branch analysis allows you to
 
 * analyze long-lived branches
diff --git a/server/sonar-docs/src/pages/branches/long-lived-branches.md b/server/sonar-docs/src/pages/branches/long-lived-branches.md
index 6498ae65888..010edc13b9c 100644
--- a/server/sonar-docs/src/pages/branches/long-lived-branches.md
+++ b/server/sonar-docs/src/pages/branches/long-lived-branches.md
@@ -2,8 +2,12 @@
 title: Long-lived Branches
 ---
 
+<!-- sonarqube -->
+
 _Branch analysis is available as part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)_
 
+<!-- /sonarqube -->
+
 ## Status vs Quality Gate
 
 The same quality gate that is applied to the project as a whole is automatically applied to long-lived branches as well. This is not editable.
diff --git a/server/sonar-docs/src/pages/branches/short-lived-branches.md b/server/sonar-docs/src/pages/branches/short-lived-branches.md
index cdf79fc9c7c..25ebadbe4ea 100644
--- a/server/sonar-docs/src/pages/branches/short-lived-branches.md
+++ b/server/sonar-docs/src/pages/branches/short-lived-branches.md
@@ -2,8 +2,12 @@
 title: Short-lived Branches
 ---
 
+<!-- sonarqube -->
+
 _Branch analysis is available as part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)_
 
+<!-- /sonarqube -->
+
 ## Status vs Quality Gate
 
 For short-lived branches, there is a kind of hard-coded quality gate focusing only on new issues. Its status is reflected by the green|red signal associated with each short-lived branch:
diff --git a/server/sonar-docs/src/pages/organizations/index.md b/server/sonar-docs/src/pages/organizations/index.md
new file mode 100644
index 00000000000..5a6fc299309
--- /dev/null
+++ b/server/sonar-docs/src/pages/organizations/index.md
@@ -0,0 +1,21 @@
+---
+title: Organizations
+scope: sonarcloud
+---
+
+## Overview
+
+An organization is a space where a team or a whole company can collaborate across many projects.
+
+An organization consists of:
+* Projects, on which users collaborate
+* [Members](/organizations/manage-team), who can have different persmissions on the projects
+* [Quality Profiles](/quality-profiles) and [Quality Gates](/quality-gates), which can be customized and shared accross projects
+
+There are 2 kind of organizations:
+* **Personal organizations**. Each account has a personal organization linked to it. This is typically where open-source developers host their personal projects. It is not possible to delete this kind of organization.
+* **Standard organization**. This is the kind of organization that users want to create for their companies or for their open-source communities. As soon as you want to collaborate, it is a good idea to create such an organization.
+
+Organizations can be on:
+* **Free plan**. This is the default plan. Every project in an organization on the free plan is public.
+* **Paid plan**. This plan unlocks the ability to have private projects. Go to the "Billing" page of your organization to upgrade it to the paid plan.
diff --git a/server/sonar-docs/src/pages/organizations/manage-team.md b/server/sonar-docs/src/pages/organizations/manage-team.md
new file mode 100644
index 00000000000..53d650f3746
--- /dev/null
+++ b/server/sonar-docs/src/pages/organizations/manage-team.md
@@ -0,0 +1,34 @@
+---
+title: Manage a Team
+scope: sonarcloud
+---
+
+Members can collaborate on the projects in the organizations to which they belong. Depending on their permisssions within the organization, members can:
+* Analyse projects
+* Manage project settings (permissions, visibility, quality profiles, ...)
+* Update issues
+* Manage quality gates and quality profiles
+* Administer the organization itself
+
+## Adding Members
+
+Adding members is done on the "Members" page of the organization, and this can be done only by an administrator of 
+the organization.
+
+Adding a user as a member is possible only if that user has already signed up on SonarCloud. If the user never authenticated to
+the system, the administrator will simply not be able to find the user in the search modal window.
+
+## Granting permissions
+
+Once added, a user can be granted permissions to perform various operations in the organization. It is up to the 
+administrator who added the user to make sure that she gets the relevant permissions.
+
+Organization admins will prefer to create groups to manage permissions, and add new users to those
+groups through the "Members" page. With such an approach, they won't have to manage individal permissions at
+project level for instance.
+
+## Future evolutions
+
+Future versions of SonarCloud will make this onboarding process easier thanks to better integrations with GitHub, 
+Bitbucket Cloud and VSTS: users won't have to sign up prior to joining an organization, and their permissions will 
+be retrieved at best from the ones existing on the other systems.
diff --git a/server/sonar-docs/src/templates/page.js b/server/sonar-docs/src/templates/page.js
index 0a4347fdabb..de57fc1a2a4 100644
--- a/server/sonar-docs/src/templates/page.js
+++ b/server/sonar-docs/src/templates/page.js
@@ -22,10 +22,13 @@ import Helmet from 'react-helmet';
 
 export default ({ data }) => {
   const page = data.markdownRemark;
-  const htmlWithInclusions = page.html.replace(/\<p\>@include (.*)\<\/p\>/, (_, path) => {
-    const chunk = data.allMarkdownRemark.edges.find(edge => edge.node.fields.slug === path);
-    return chunk ? chunk.node.html : '';
-  });
+  const htmlWithInclusions = cutSonarCloudContent(page.html).replace(
+    /\<p\>@include (.*)\<\/p\>/,
+    (_, path) => {
+      const chunk = data.allMarkdownRemark.edges.find(edge => edge.node.fields.slug === path);
+      return chunk ? chunk.node.html : '';
+    }
+  );
 
   return (
     <div css={{ paddingTop: 24, paddingBottom: 24 }}>
@@ -56,3 +59,19 @@ export const query = graphql`
     }
   }
 `;
+
+function cutSonarCloudContent(content) {
+  const beginning = '<!-- sonarcloud -->';
+  const ending = '<!-- /sonarcloud -->';
+
+  let newContent = content;
+  let start = newContent.indexOf(beginning);
+  let end = newContent.indexOf(ending);
+  while (start !== -1 && end !== -1) {
+    newContent = newContent.substring(0, start) + newContent.substring(end + ending.length);
+    start = newContent.indexOf(beginning);
+    end = newContent.indexOf(ending);
+  }
+
+  return newContent;
+}
diff --git a/server/sonar-docs/src/tooltips/organizations/add-organization-member.md b/server/sonar-docs/src/tooltips/organizations/add-organization-member.md
new file mode 100644
index 00000000000..ef8bd37c141
--- /dev/null
+++ b/server/sonar-docs/src/tooltips/organizations/add-organization-member.md
@@ -0,0 +1,5 @@
+Add new members to this organization and manage their permissions. Note that users must have signed up on the service to be able to find and add them.
+
+---
+
+See also: [Manage a Team](/organizations/manage-team)