From 1ecc01852f61d7683995beac1206bb95a6e5e6ae Mon Sep 17 00:00:00 2001 From: michaelbirnstiehl Date: Mon, 9 Dec 2019 11:29:10 -0600 Subject: [PATCH] DOCS replace fix the leak with clean as you code --- .../sonar-docs/src/EmbedDocsSuggestions.json | 20 +++++----- .../src/pages/analysis/scm-integration.md | 2 +- server/sonar-docs/src/pages/index.md | 2 +- .../project-administration/new-code-period.md | 2 +- .../src/pages/user-guide/clean-as-you-code.md | 37 +++++++++++++++++++ .../pages/user-guide/fixing-the-water-leak.md | 37 ------------------- .../src/pages/user-guide/project-page.md | 2 +- .../src/pages/user-guide/quality-gates.md | 2 +- .../quality-gates/quality-gate-conditions.md | 2 +- .../static/SonarCloudNavigationTree.json | 2 +- .../static/SonarQubeNavigationTree.json | 2 +- .../static/StaticNavigationTree.json | 2 +- .../resources/org/sonar/l10n/core.properties | 4 +- 13 files changed, 58 insertions(+), 58 deletions(-) create mode 100644 server/sonar-docs/src/pages/user-guide/clean-as-you-code.md delete mode 100644 server/sonar-docs/src/pages/user-guide/fixing-the-water-leak.md diff --git a/server/sonar-docs/src/EmbedDocsSuggestions.json b/server/sonar-docs/src/EmbedDocsSuggestions.json index aeca5c1a53a..a1f10d7b4cd 100644 --- a/server/sonar-docs/src/EmbedDocsSuggestions.json +++ b/server/sonar-docs/src/EmbedDocsSuggestions.json @@ -20,8 +20,8 @@ ], "component_measures": [ { - "link": "/documentation/user-guide/fixing-the-water-leak/", - "text": "Fixing the Water Leak" + "link": "/documentation/user-guide/clean-as-you-code/", + "text": "Clean as You Code" }, { "link": "/documentation/user-guide/metric-definitions/", @@ -88,8 +88,8 @@ ], "overview": [ { - "link": "/documentation/user-guide/fixing-the-water-leak/", - "text": "Fixing the Water Leak" + "link": "/documentation/user-guide/clean-as-you-code/", + "text": "Clean as You Code" }, { "link": "/documentation/branches/overview/", @@ -116,8 +116,8 @@ ], "project_quality_gate": [ { - "link": "/documentation/user-guide/fixing-the-water-leak/", - "text": "Fixing the Water Leak" + "link": "/documentation/user-guide/clean-as-you-code/", + "text": "Clean as You Code" } ], "project_quality_profiles": [ @@ -142,8 +142,8 @@ ], "pull_requests": [ { - "link": "/documentation/user-guide/fixing-the-water-leak/", - "text": "Fixing the Water Leak" + "link": "/documentation/user-guide/clean-as-you-code/", + "text": "Clean as You Code" }, { "link": "/documentation/analysis/pull-request/", @@ -152,8 +152,8 @@ ], "quality_gates": [ { - "link": "/documentation/user-guide/fixing-the-water-leak/", - "text": "Fixing the Water Leak" + "link": "/documentation/user-guide/clean-as-you-code/", + "text": "Clean as You Code" } ], "quality_profiles": [ diff --git a/server/sonar-docs/src/pages/analysis/scm-integration.md b/server/sonar-docs/src/pages/analysis/scm-integration.md index dd2ac40e4a2..e2ddf58b21f 100644 --- a/server/sonar-docs/src/pages/analysis/scm-integration.md +++ b/server/sonar-docs/src/pages/analysis/scm-integration.md @@ -7,7 +7,7 @@ Collecting SCM data during code analysis can unlock a number of SonarQube featur * Automatic Issue Assignment * code annotation (blame data) in the Code Viewer -* SCM-driven detection of new code (to help with [Fixing the Water Leak](/user-guide/fixing-the-water-leak/)). Without SCM data, SonarQube determines new code using analysis dates (to timestamp modification of lines). +* SCM-driven detection of new code (to help with [Clean as You Code](/user-guide/clean-as-you-code/)). Without SCM data, SonarQube determines new code using analysis dates (to timestamp modification of lines). SCM integration requires support for your individual SCM provider. Git and SVN are supported by default. For other SCM providers, see the Marketplace. diff --git a/server/sonar-docs/src/pages/index.md b/server/sonar-docs/src/pages/index.md index 600d9a5d50a..673bc333e02 100644 --- a/server/sonar-docs/src/pages/index.md +++ b/server/sonar-docs/src/pages/index.md @@ -38,7 +38,7 @@ Below are a few key pointers, otherwise head over to the left pane for full docu * [Pull Requests](/analysis/pull-request/) ### I write code -* Why [new code](/user-guide/fixing-the-water-leak/) is the most important +* Why [new code](/user-guide/clean-as-you-code/) is the most important * [Concepts](/user-guide/concepts/) * [Quality Gates](/user-guide/quality-gates/) * [Issues](/user-guide/issues/) diff --git a/server/sonar-docs/src/pages/project-administration/new-code-period.md b/server/sonar-docs/src/pages/project-administration/new-code-period.md index f4887b179b1..2d710648511 100644 --- a/server/sonar-docs/src/pages/project-administration/new-code-period.md +++ b/server/sonar-docs/src/pages/project-administration/new-code-period.md @@ -2,7 +2,7 @@ title: Setting Your New Code Period url: /project-administration/new-code-period/ --- -By focusing on code that's been added or changed in your New Code Period, you can set consistent quality requirements and expectations on all new code. With this focus, your new code will be issue-free and you'll clean up the code you encounter along the way. For more information on the New Code Period and Cleaning as You Code, check out [Fixing the Water Leak](/user-guide/fixing-the-water-leak/). +By focusing on code that's been added or changed in your New Code Period, you can set consistent quality requirements and expectations on all new code. With this focus, your new code will be issue-free and you'll clean up the code you encounter along the way. For more information on the New Code Period, see the [Clean as You Code](/user-guide/clean-as-you-code/) page. You can set a New Code Period at the global, project, or branch level. diff --git a/server/sonar-docs/src/pages/user-guide/clean-as-you-code.md b/server/sonar-docs/src/pages/user-guide/clean-as-you-code.md new file mode 100644 index 00000000000..69b285eb5d7 --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/clean-as-you-code.md @@ -0,0 +1,37 @@ +--- +title: Clean as You Code +url: /user-guide/clean-as-you-code/ +--- + +## What is Clean as You Code? + +Clean as You Code is an approach to Code Quality that eliminates a lot of the challenges that come with traditional approaches. As a developer, you focus on maintaining high standards and taking responsibility specifically in the New Code you're working on. SonarQube gives you the tools that let you set high standards and take pride in knowing that your code meets those standards. + +## Focus on New Code + +With Clean as You Code, your focus is always on New Code (code that has been added or changed in your New Code Period) and making sure the code you write today is clean and safe. + +The New Code Period can be set at different levels (global, project, and with [Developer Edition](https://redirect.sonarsource.com/editions/developer.html) and [above](https://www.sonarsource.com/plans-and-pricing/) at the branch level). Depending on the level at which your New Code Period is set, you can change the starting point of your New Code Period to fit your situation. + +For more information on the New Code Period and setting it, check out [Setting Your New Code Period](/project-administration/new-code-period/). + +## Personal Responsibility + +With Clean as You Code, you aren't responsible for anyone else's code. You own the quality and security of the New Code you are working on today. If you add new issues, SonarQube automatically assigns them to you so you can maintain quality in your code. + +For more information on issues and how they are assigned, check out the [Issues](/user-guide/issues/) documentation. + +## Quality Gate + +Your Quality Gate is a set of conditions that tells you whether or not your project is ready for release. With the Clean as You Code approach, your Quality Gate should: + +* **Focus on New Code metrics** – When your Quality Gate is set to focus on New Code metrics (like the built-in Sonar way Quality Gate), new features will be delivered cleanly. As long as your Quality gate is green, your releases will continue to improve. +* **Set and enforce high standards** – When standards are set and enforced on New Code, you aren't worried about having to meet those standards in old code and having to clean up someone else's code. You can take pride in meeting high standards on _your_ code. If a project doesn't meet these high standards, it won't pass the Quality Gate, and it's obviously not ready to be released. + +For more information on Quality Gates and making sure your Quality Gate is enforcing your standards, check out the [Quality Gates](/user-guide/quality-gates/) documentation. + +## Pull Request Analysis + +You can use Pull Request analysis and decoration to make sure your code is meeting your standards before you merge. Pull Request analysis lets you see your Pull Request's Quality Gate in the SonarQube UI. You can then decorate your Pull Requests with SonarQube issues directly in your ALM's interface. + +For more information on setting up Pull Request analysis and decoration, see the [Pull Request](/analysis/pull-request/) documentation. \ No newline at end of file diff --git a/server/sonar-docs/src/pages/user-guide/fixing-the-water-leak.md b/server/sonar-docs/src/pages/user-guide/fixing-the-water-leak.md deleted file mode 100644 index 59927ff5eb7..00000000000 --- a/server/sonar-docs/src/pages/user-guide/fixing-the-water-leak.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Fixing the Water Leak -url: /user-guide/fixing-the-water-leak/ ---- - -## What is the Water Leak - -Imagine coming home one day to find a puddle of water on the kitchen floor. As the puddle grows, do you start mopping or do you find the leak and plug it? - -The answer is obvious, right? You fix the leak! - -So why do anything different with code quality? When you analyze an application with {instance} and realize that it has a lot of technical debt, your initial reaction may be to start remediating or to put together a remediation plan. This is like mopping the floor while ignoring the fact that water is still leaking. - -Typically in this remediation-first approach, a periodic code quality audit, often right before release, results in findings the developers should act on. This approach consistently fails because: - -* The code review comes too late in the process, and no stakeholder is keen to get the problems fixed; everyone wants the new version to ship. -* Developers typically push back on recommendations made by an external team that doesn't know the context of the project. And, by the way, the code under review is obsolete already. -* There is a clear lack of ownership for code quality with this approach. Who owns quality? No one! -* What gets reviewed is the entire application before it goes to production and it is obviously not possible to apply the same criteria to all applications. A negotiation will happen for each project, which will drain all credibility from the process - -Instead, why not apply the same simple logic you use at home to the way you manage code quality? Fixing the leak means focusing on the “new” code, for example, code that was added or changed after the last release. Then things get much easier: - -* The [Quality Gate](/user-guide/quality-gates/) can be run every day, and passing it is achievable. There are no surprises at release time. -* It's pretty difficult for developers to push back on problems they introduced the previous day. Instead, they're generally happy to fix the problems while the code is still fresh. -* There is a clear ownership of code quality -* The criteria for go/no-go are consistent across applications, and are shared among teams. Indeed new code is new code, regardless of which application it is done in -* The cost is insignificant because it is part of the development process - -As a bonus, the code that gets changed the most has the highest maintainability, and the code that doesn't get changed has the lowest, which makes a lot of sense. Because of the nature of software, and the fact that we keep making changes to it, the debt will naturally be reduced. Where it isn’t is where it doesn't need to be. - -## How to do it - -{instance} offers two main tools to help you find your leaks: - -* New Code metrics show the variance in your measures between the current code and a specific point you choose in its history, typically the previous version of the project. For more information, see [Setting Your New Code Period](/project-administration/new-code-period/) page for more information on setting up your New Code Period. -* New Code is primarily detected based on SCM "blame" data starting from the first analysis within your New Code Period, with fallback mechanisms when needed. See [SCM integration](/analysis/scm-integration/) for more details. -* [Quality Gates](/user-guide/quality-gates/) allow you to set boolean thresholds against which your code is measured. Use them with differential metrics to ensure that your code quality moves in the right direction over time. diff --git a/server/sonar-docs/src/pages/user-guide/project-page.md b/server/sonar-docs/src/pages/user-guide/project-page.md index d9e679e5eaf..24d2149b421 100644 --- a/server/sonar-docs/src/pages/user-guide/project-page.md +++ b/server/sonar-docs/src/pages/user-guide/project-page.md @@ -7,7 +7,7 @@ url: /user-guide/project-page/ The Project Hompepage is the entry point of any project showing: * the releasability status of the project * the current state of its quality -* the quality of what has been produced since the beginning of its [New Code Period](/user-guide/fixing-the-water-leak/). +* the quality of what has been produced since the beginning of its [New Code Period](/user-guide/clean-as-you-code/). The Project Page answers two questions: diff --git a/server/sonar-docs/src/pages/user-guide/quality-gates.md b/server/sonar-docs/src/pages/user-guide/quality-gates.md index 623fb2d0815..5d7bc56d721 100644 --- a/server/sonar-docs/src/pages/user-guide/quality-gates.md +++ b/server/sonar-docs/src/pages/user-guide/quality-gates.md @@ -24,7 +24,7 @@ Which is why you can define as many quality gates as you wish. Quality Gates are ## Use the Best Quality Gate Configuration -The quality gate "Sonar way" is provided by SonarSource, activated by default and considered as built-in and so read-only. It represents our view of the best way to implement the [Fixing the Water Leak](/user-guide/fixing-the-water-leak/) concept. At each SonarQube release, we adjust automatically this default quality gate according to SonarQube's capabilities. +The quality gate "Sonar way" is provided by SonarSource, activated by default and considered as built-in and so read-only. It represents our view of the best way to implement the [Clean as You Code](/user-guide/clean-as-you-code/) concept. At each SonarQube release, we adjust automatically this default quality gate according to SonarQube's capabilities. Three metrics allow you to enforce a given Rating of Reliability, Security and Maintainability, not just overall but also on new code. These metrics are recommended and come as part of the default quality gate. We strongly advise you to adjust your own quality gates to use them to make feedback more clear to your developers looking at their quality gate on their project page. diff --git a/server/sonar-docs/src/tooltips/quality-gates/quality-gate-conditions.md b/server/sonar-docs/src/tooltips/quality-gates/quality-gate-conditions.md index 66dc9a705cd..c083804769e 100644 --- a/server/sonar-docs/src/tooltips/quality-gates/quality-gate-conditions.md +++ b/server/sonar-docs/src/tooltips/quality-gates/quality-gate-conditions.md @@ -2,4 +2,4 @@ Both conditions on New Code and Overall Code have to be met by a project to pass --- -See also: [Fixing the Water Leak](/user-guide/fixing-the-water-leak/) +See also: [Clean as You Code](/user-guide/clean-as-you-code/) diff --git a/server/sonar-docs/static/SonarCloudNavigationTree.json b/server/sonar-docs/static/SonarCloudNavigationTree.json index 914954da250..4b8c1bd64ba 100644 --- a/server/sonar-docs/static/SonarCloudNavigationTree.json +++ b/server/sonar-docs/static/SonarCloudNavigationTree.json @@ -51,7 +51,7 @@ { "title": "User Guide", "children": [ - "/user-guide/fixing-the-water-leak/", + "/user-guide/clean-as-you-code/", "/user-guide/project-page/", "/user-guide/issues/", "/user-guide/security-hotspots/", diff --git a/server/sonar-docs/static/SonarQubeNavigationTree.json b/server/sonar-docs/static/SonarQubeNavigationTree.json index 997d70f9806..b42911fecda 100644 --- a/server/sonar-docs/static/SonarQubeNavigationTree.json +++ b/server/sonar-docs/static/SonarQubeNavigationTree.json @@ -81,7 +81,7 @@ { "title": "User Guide", "children": [ - "/user-guide/fixing-the-water-leak/", + "/user-guide/clean-as-you-code/", "/user-guide/project-page/", "/user-guide/applications/", "/user-guide/portfolios/", diff --git a/server/sonar-docs/static/StaticNavigationTree.json b/server/sonar-docs/static/StaticNavigationTree.json index 58a3e1998f0..b5abb6864e4 100644 --- a/server/sonar-docs/static/StaticNavigationTree.json +++ b/server/sonar-docs/static/StaticNavigationTree.json @@ -97,7 +97,7 @@ { "title": "User Guide", "children": [ - "/user-guide/fixing-the-water-leak/", + "/user-guide/clean-as-you-code/", "/user-guide/project-page/", "/user-guide/applications/", "/user-guide/portfolios/", diff --git a/sonar-core/src/main/resources/org/sonar/l10n/core.properties b/sonar-core/src/main/resources/org/sonar/l10n/core.properties index 92ad826cd9d..0499a54c10c 100644 --- a/sonar-core/src/main/resources/org/sonar/l10n/core.properties +++ b/sonar-core/src/main/resources/org/sonar/l10n/core.properties @@ -2792,8 +2792,8 @@ about_page.quality_model.security_hotspots=are raised on security-sensitive code about_page.clean_code=Write Clean Code about_page.clean_code.text=By fixing new issues as they appear in code, you create and maintain a clean code base. Even on legacy projects, focusing on keeping new code clean will eventually yield a code base you can be proud of. -about_page.fix_the_leak=Fix The Leak -about_page.fix_the_leak_on_new_code.text=The water leak paradigm and the default Quality Gate are based on the new code period - the recent period against which you're tracking issues. For some previous_version makes the most sense, for others the last 30 days is a good option. +about_page.fix_the_leak=Clean as You Code +about_page.fix_the_leak_on_new_code.text=The Clean as You Code approach and the default Quality Gate are based on the new code period - the recent period against which you're tracking issues. For some previous_version makes the most sense, for others the last 30 days is a good option. about_page.quality_gates=Enforce Quality Gate about_page.quality_gates.text=Your project's Quality Gate is the set of conditions the project must meet before it can be released into production. The Quality Gate is designed to ensure that the next version's quality will be better than the last. -- 2.39.5