From b36a9040f3551270d7a9e7546117b7d9fd15bd80 Mon Sep 17 00:00:00 2001
From: Paul Melnikow <github@paulmelnikow.com>
Date: Tue, 18 Dec 2018 15:52:17 -0500
Subject: [PATCH] Add warning banners to legacy services (#2546)

---
 services/amo/amo.service.js                          |  6 ++++++
 services/bintray/bintray.service.js                  |  6 ++++++
 services/bitrise/bitrise.service.js                  |  6 ++++++
 services/bower/bower-license.service.js              |  6 ++++++
 services/bower/bower-version.service.js              |  6 ++++++
 services/bugzilla/bugzilla.service.js                |  6 ++++++
 services/buildkite/buildkite.service.js              |  6 ++++++
 services/bundlephobia/bundlephobia.service.js        |  7 ++++++-
 .../chrome-web-store/chrome-web-store.service.js     |  6 ++++++
 services/cocoapods/cocoapods-apps.service.js         |  6 ++++++
 services/cocoapods/cocoapods-downloads.service.js    |  6 ++++++
 services/cocoapods/cocoapods-metrics.service.js      |  6 ++++++
 services/cocoapods/cocoapods.service.js              |  6 ++++++
 services/codeclimate/codeclimate.service.js          |  6 ++++++
 services/codecov/codecov.service.js                  |  6 ++++++
 services/codeship/codeship.service.js                |  6 ++++++
 services/continuousphp/continuousphp.service.js      |  6 ++++++
 services/cookbook/cookbook.service.js                |  7 +++++++
 services/coveralls/coveralls.service.js              |  6 ++++++
 services/coverity/coverity-on-demand.service.js      |  7 +++++++
 services/coverity/coverity-scan.service.js           |  6 ++++++
 services/cpan/cpan.service.js                        |  6 ++++++
 services/david/david.service.js                      |  6 ++++++
 services/discourse/discourse.service.js              |  6 ++++++
 services/dub/dub-download.service.js                 |  6 ++++++
 services/dub/dub-license-version.service.js          |  6 ++++++
 services/github/github-commit-activity.service.js    |  6 ++++++
 services/github/github-commit-status.service.js      |  6 ++++++
 services/github/github-commits-since.service.js      |  6 ++++++
 services/github/github-contributors.service.js       |  6 ++++++
 services/github/github-downloads.service.js          |  6 ++++++
 services/github/github-followers.service.js          |  6 ++++++
 services/github/github-forks.service.js              |  6 ++++++
 services/github/github-issue-detail.service.js       |  6 ++++++
 services/github/github-issues.service.js             |  6 ++++++
 services/github/github-languages.service.js          |  6 ++++++
 services/github/github-last-commit.service.js        |  6 ++++++
 services/github/github-license.service.js            |  6 ++++++
 services/github/github-manifest-version.service.js   |  6 ++++++
 services/github/github-release-date.service.js       |  6 ++++++
 services/github/github-release.service.js            |  6 ++++++
 services/github/github-repo-size.service.js          |  6 ++++++
 services/github/github-search.service.js             |  6 ++++++
 services/github/github-size.service.js               |  6 ++++++
 services/github/github-stars.service.js              |  6 ++++++
 services/github/github-tag.service.js                |  6 ++++++
 services/github/github-watchers.service.js           |  6 ++++++
 services/hackage/hackage-deps.service.js             |  6 ++++++
 services/hackage/hackage-version.service.js          |  6 ++++++
 services/homebrew/homebrew.service.js                |  6 ++++++
 services/itunes/itunes.service.js                    |  6 ++++++
 services/jenkins/jenkins-build.service.js            |  6 ++++++
 services/jenkins/jenkins-plugin-version.service.js   |  6 ++++++
 services/jenkins/jenkins-tests.service.js            |  6 ++++++
 services/jitpack/jitpack.service.js                  |  6 ++++++
 services/lgtm/lgtm-alerts.service.js                 |  6 ++++++
 services/lgtm/lgtm-grade.service.js                  |  6 ++++++
 services/liberapay/liberapay.service.js              |  6 ++++++
 .../librariesio/librariesio-dependencies.service.js  |  6 ++++++
 services/luarocks/luarocks.service.js                |  6 ++++++
 services/maintenance/maintenance.service.js          |  6 ++++++
 services/maven-central/maven-central.service.js      |  8 +++++++-
 services/maven-metadata/maven-metadata.service.js    |  6 ++++++
 services/microbadger/microbadger.service.js          |  6 ++++++
 services/nexus/nexus.service.js                      |  6 ++++++
 services/osstracker/osstracker.service.js            |  7 +++++++
 services/packagecontrol/packagecontrol.service.js    |  6 ++++++
 services/packagist/packagist-downloads.service.js    |  6 ++++++
 services/packagist/packagist-license.service.js      |  6 ++++++
 services/packagist/packagist-php-version.service.js  |  6 ++++++
 services/packagist/packagist-version.service.js      |  6 ++++++
 services/php-eye/php-eye-hhvm.service.js             |  6 ++++++
 services/php-eye/php-eye-php-version.service.js      |  6 ++++++
 services/pub/pub.service.js                          |  7 +++++++
 services/puppetforge/puppetforge-modules.service.js  |  6 ++++++
 services/puppetforge/puppetforge-users.service.js    |  6 ++++++
 services/scrutinizer/scrutinizer.service.js          |  6 ++++++
 services/sensiolabs/sensiolabs.service.js            |  6 ++++++
 services/shippable/shippable.service.js              |  6 ++++++
 services/sonarqube/sonarqube.service.js              |  6 ++++++
 services/sourceforge/sourceforge.service.js          |  6 ++++++
 services/teamcity/teamcity-build.service.js          |  6 ++++++
 services/teamcity/teamcity-coverage.service.js       |  6 ++++++
 services/travis/travis-build.service.js              |  7 +++++++
 services/travis/travis-php-version.service.js        |  6 ++++++
 services/twitter/twitter.service.js                  | 12 ++++++++++++
 .../vaadin-directory/vaadin-directory.service.js     |  6 ++++++
 .../vscode-marketplace/vscode-marketplace.service.js |  7 +++++++
 services/waffle/waffle.service.js                    |  6 ++++++
 services/website/website.service.js                  |  6 ++++++
 90 files changed, 553 insertions(+), 2 deletions(-)

diff --git a/services/amo/amo.service.js b/services/amo/amo.service.js
index da123461f6..0c2822c3be 100644
--- a/services/amo/amo.service.js
+++ b/services/amo/amo.service.js
@@ -150,6 +150,12 @@ class AmoUsers extends LegacyService {
   static registerLegacyRouteHandler() {}
 }
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 class Amo extends LegacyService {
   static registerLegacyRouteHandler({ camp, cache }) {
     camp.route(
diff --git a/services/bintray/bintray.service.js b/services/bintray/bintray.service.js
index 5ef5db57d9..1862b36fee 100644
--- a/services/bintray/bintray.service.js
+++ b/services/bintray/bintray.service.js
@@ -6,6 +6,12 @@ const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 const serverSecrets = require('../../lib/server-secrets')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Bintray extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/bitrise/bitrise.service.js b/services/bitrise/bitrise.service.js
index 874fba7375..0c6a1242ed 100644
--- a/services/bitrise/bitrise.service.js
+++ b/services/bitrise/bitrise.service.js
@@ -3,6 +3,12 @@
 const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Bitrise extends LegacyService {
   static get category() {
     return 'build'
diff --git a/services/bower/bower-license.service.js b/services/bower/bower-license.service.js
index 4d88b7ffe9..b3cbe261fd 100644
--- a/services/bower/bower-license.service.js
+++ b/services/bower/bower-license.service.js
@@ -4,6 +4,12 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const serverSecrets = require('../../lib/server-secrets')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class BowerLicense extends LegacyService {
   static get category() {
     return 'license'
diff --git a/services/bower/bower-version.service.js b/services/bower/bower-version.service.js
index 9987b4b9f6..209e7b99c4 100644
--- a/services/bower/bower-version.service.js
+++ b/services/bower/bower-version.service.js
@@ -6,6 +6,12 @@ const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 const serverSecrets = require('../../lib/server-secrets')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class BowerVersion extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/bugzilla/bugzilla.service.js b/services/bugzilla/bugzilla.service.js
index ec4e8b7249..077ab09c73 100644
--- a/services/bugzilla/bugzilla.service.js
+++ b/services/bugzilla/bugzilla.service.js
@@ -10,6 +10,12 @@ const documentation = `
 </p>
 `
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Bugzilla extends LegacyService {
   static get category() {
     return 'issue-tracking'
diff --git a/services/buildkite/buildkite.service.js b/services/buildkite/buildkite.service.js
index 627f814b19..f51cb41392 100644
--- a/services/buildkite/buildkite.service.js
+++ b/services/buildkite/buildkite.service.js
@@ -4,6 +4,12 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const { checkErrorResponse } = require('../../lib/error-helper')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Buildkite extends LegacyService {
   static get category() {
     return 'build'
diff --git a/services/bundlephobia/bundlephobia.service.js b/services/bundlephobia/bundlephobia.service.js
index ba0bb8d381..164f7c5f0e 100644
--- a/services/bundlephobia/bundlephobia.service.js
+++ b/services/bundlephobia/bundlephobia.service.js
@@ -4,7 +4,12 @@ const prettyBytes = require('pretty-bytes')
 const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 
-// Bundle size for npm packages.
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Bundlephobia extends LegacyService {
   static get category() {
     return 'size'
diff --git a/services/chrome-web-store/chrome-web-store.service.js b/services/chrome-web-store/chrome-web-store.service.js
index 1a1e748cdd..916e20a8fe 100644
--- a/services/chrome-web-store/chrome-web-store.service.js
+++ b/services/chrome-web-store/chrome-web-store.service.js
@@ -137,6 +137,12 @@ class ChromeWebStoreRating extends LegacyService {
   static registerLegacyRouteHandler() {}
 }
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 class ChromeWebStore extends LegacyService {
   static registerLegacyRouteHandler({ camp, cache }) {
     camp.route(
diff --git a/services/cocoapods/cocoapods-apps.service.js b/services/cocoapods/cocoapods-apps.service.js
index f4e63588f6..2d21098ade 100644
--- a/services/cocoapods/cocoapods-apps.service.js
+++ b/services/cocoapods/cocoapods-apps.service.js
@@ -8,6 +8,12 @@ const {
   downloadCount: downloadCountColor,
 } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class CocoapodsApps extends LegacyService {
   static get category() {
     return 'other'
diff --git a/services/cocoapods/cocoapods-downloads.service.js b/services/cocoapods/cocoapods-downloads.service.js
index 2a3d71061e..80387e5da1 100644
--- a/services/cocoapods/cocoapods-downloads.service.js
+++ b/services/cocoapods/cocoapods-downloads.service.js
@@ -8,6 +8,12 @@ const {
   downloadCount: downloadCountColor,
 } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class CocoapodsDownloads extends LegacyService {
   static get category() {
     return 'downloads'
diff --git a/services/cocoapods/cocoapods-metrics.service.js b/services/cocoapods/cocoapods-metrics.service.js
index 2c9c0e63ea..f9fcdfc1a9 100644
--- a/services/cocoapods/cocoapods-metrics.service.js
+++ b/services/cocoapods/cocoapods-metrics.service.js
@@ -7,6 +7,12 @@ const {
   coveragePercentage: coveragePercentageColor,
 } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class CocoapodsMetrics extends LegacyService {
   static get category() {
     return 'quality'
diff --git a/services/cocoapods/cocoapods.service.js b/services/cocoapods/cocoapods.service.js
index c8fff7913c..147e0f347e 100644
--- a/services/cocoapods/cocoapods.service.js
+++ b/services/cocoapods/cocoapods.service.js
@@ -6,6 +6,12 @@ const { checkErrorResponse } = require('../../lib/error-helper')
 const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class CocoapodsVersionPlatformLicense extends LegacyService {
   static registerLegacyRouteHandler({ camp, cache }) {
     camp.route(
diff --git a/services/codeclimate/codeclimate.service.js b/services/codeclimate/codeclimate.service.js
index e7f7b9483c..27d05ea262 100644
--- a/services/codeclimate/codeclimate.service.js
+++ b/services/codeclimate/codeclimate.service.js
@@ -8,6 +8,12 @@ const {
   colorScale,
 } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Codeclimate extends LegacyService {
   static registerLegacyRouteHandler({ camp, cache }) {
     camp.route(
diff --git a/services/codecov/codecov.service.js b/services/codecov/codecov.service.js
index 91c6865970..50b7cdc1b6 100644
--- a/services/codecov/codecov.service.js
+++ b/services/codecov/codecov.service.js
@@ -7,6 +7,12 @@ const {
   coveragePercentage: coveragePercentageColor,
 } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Codecov extends LegacyService {
   static get category() {
     return 'quality'
diff --git a/services/codeship/codeship.service.js b/services/codeship/codeship.service.js
index 7db76356dc..e1e884f923 100644
--- a/services/codeship/codeship.service.js
+++ b/services/codeship/codeship.service.js
@@ -3,6 +3,12 @@
 const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Codeship extends LegacyService {
   static get category() {
     return 'build'
diff --git a/services/continuousphp/continuousphp.service.js b/services/continuousphp/continuousphp.service.js
index f6c2528aa4..5ab44ad6db 100644
--- a/services/continuousphp/continuousphp.service.js
+++ b/services/continuousphp/continuousphp.service.js
@@ -3,6 +3,12 @@
 const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class ContinuousPhp extends LegacyService {
   static get category() {
     return 'build'
diff --git a/services/cookbook/cookbook.service.js b/services/cookbook/cookbook.service.js
index b0556ba796..e745e864f2 100644
--- a/services/cookbook/cookbook.service.js
+++ b/services/cookbook/cookbook.service.js
@@ -6,6 +6,13 @@ const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 
 // For Chef cookbook.
+//
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Cookbook extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/coveralls/coveralls.service.js b/services/coveralls/coveralls.service.js
index ac27e30865..3d221d541c 100644
--- a/services/coveralls/coveralls.service.js
+++ b/services/coveralls/coveralls.service.js
@@ -6,6 +6,12 @@ const {
   coveragePercentage: coveragePercentageColor,
 } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Coveralls extends LegacyService {
   static get category() {
     return 'quality'
diff --git a/services/coverity/coverity-on-demand.service.js b/services/coverity/coverity-on-demand.service.js
index ebb19a3503..ea6217d02c 100644
--- a/services/coverity/coverity-on-demand.service.js
+++ b/services/coverity/coverity-on-demand.service.js
@@ -4,6 +4,13 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 
 // For Coverity Code Advisor On Demand.
+//
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class CoverityOnDemand extends LegacyService {
   static get category() {
     return 'quality'
diff --git a/services/coverity/coverity-scan.service.js b/services/coverity/coverity-scan.service.js
index 68f9ed6df7..3ca687ebc9 100644
--- a/services/coverity/coverity-scan.service.js
+++ b/services/coverity/coverity-scan.service.js
@@ -3,6 +3,12 @@
 const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class CoverityScan extends LegacyService {
   static get category() {
     return 'quality'
diff --git a/services/cpan/cpan.service.js b/services/cpan/cpan.service.js
index e2e97eaa4d..7b265fda95 100644
--- a/services/cpan/cpan.service.js
+++ b/services/cpan/cpan.service.js
@@ -5,6 +5,12 @@ const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Cpan extends LegacyService {
   static get route() {
     return { base: 'cpan' }
diff --git a/services/david/david.service.js b/services/david/david.service.js
index ce41521058..5ae15c5e96 100644
--- a/services/david/david.service.js
+++ b/services/david/david.service.js
@@ -3,6 +3,12 @@
 const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class David extends LegacyService {
   static get category() {
     return 'dependencies'
diff --git a/services/discourse/discourse.service.js b/services/discourse/discourse.service.js
index 4d9e079933..d2b867556e 100644
--- a/services/discourse/discourse.service.js
+++ b/services/discourse/discourse.service.js
@@ -4,6 +4,12 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const { metric } = require('../../lib/text-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Discourse extends LegacyService {
   static get category() {
     return 'chat'
diff --git a/services/dub/dub-download.service.js b/services/dub/dub-download.service.js
index c92fb65039..0b76d6b99c 100644
--- a/services/dub/dub-download.service.js
+++ b/services/dub/dub-download.service.js
@@ -12,6 +12,12 @@ const {
   downloadCount: downloadCountColor,
 } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class DubDownload extends LegacyService {
   static get category() {
     return 'downloads'
diff --git a/services/dub/dub-license-version.service.js b/services/dub/dub-license-version.service.js
index 5c0c8967f1..587db9f487 100644
--- a/services/dub/dub-license-version.service.js
+++ b/services/dub/dub-license-version.service.js
@@ -59,6 +59,12 @@ class DubLicense extends LegacyService {
   static registerLegacyRouteHandler() {}
 }
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 class DubLicenseVersion extends LegacyService {
   static registerLegacyRouteHandler({ camp, cache }) {
     camp.route(
diff --git a/services/github/github-commit-activity.service.js b/services/github/github-commit-activity.service.js
index 11dd3e2742..2c2bef12fc 100644
--- a/services/github/github-commit-activity.service.js
+++ b/services/github/github-commit-activity.service.js
@@ -11,6 +11,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubCommitActivity extends LegacyService {
   static get category() {
     return 'activity'
diff --git a/services/github/github-commit-status.service.js b/services/github/github-commit-status.service.js
index 0838f2962d..7001345a88 100644
--- a/services/github/github-commit-status.service.js
+++ b/services/github/github-commit-status.service.js
@@ -7,6 +7,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubCommitStatus extends LegacyService {
   static get category() {
     return 'issue-tracking'
diff --git a/services/github/github-commits-since.service.js b/services/github/github-commits-since.service.js
index b2ef6f069d..1f064a2ab0 100644
--- a/services/github/github-commits-since.service.js
+++ b/services/github/github-commits-since.service.js
@@ -10,6 +10,12 @@ const { documentation } = require('./github-helpers')
 
 const keywords = ['GitHub', 'commit']
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubCommitsSince extends LegacyService {
   static get category() {
     return 'activity'
diff --git a/services/github/github-contributors.service.js b/services/github/github-contributors.service.js
index aa184a7dc7..3e48157c93 100644
--- a/services/github/github-contributors.service.js
+++ b/services/github/github-contributors.service.js
@@ -11,6 +11,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubContributors extends LegacyService {
   static get category() {
     return 'activity'
diff --git a/services/github/github-downloads.service.js b/services/github/github-downloads.service.js
index 3b7bbbacaa..15b1808d17 100644
--- a/services/github/github-downloads.service.js
+++ b/services/github/github-downloads.service.js
@@ -11,6 +11,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubDownloads extends LegacyService {
   static get category() {
     return 'downloads'
diff --git a/services/github/github-followers.service.js b/services/github/github-followers.service.js
index a813d8e9e1..de996ee14e 100644
--- a/services/github/github-followers.service.js
+++ b/services/github/github-followers.service.js
@@ -10,6 +10,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubFollowers extends LegacyService {
   static get category() {
     return 'social'
diff --git a/services/github/github-forks.service.js b/services/github/github-forks.service.js
index d7800820a3..cb4dae45f0 100644
--- a/services/github/github-forks.service.js
+++ b/services/github/github-forks.service.js
@@ -10,6 +10,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubForks extends LegacyService {
   static get category() {
     return 'social'
diff --git a/services/github/github-issue-detail.service.js b/services/github/github-issue-detail.service.js
index fbbddb0b33..65c6e82af3 100644
--- a/services/github/github-issue-detail.service.js
+++ b/services/github/github-issue-detail.service.js
@@ -16,6 +16,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubIssueDetail extends LegacyService {
   static get category() {
     return 'issue-tracking'
diff --git a/services/github/github-issues.service.js b/services/github/github-issues.service.js
index 475b9012d4..adc7d9c42e 100644
--- a/services/github/github-issues.service.js
+++ b/services/github/github-issues.service.js
@@ -11,6 +11,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubIssues extends LegacyService {
   static get category() {
     return 'issue-tracking'
diff --git a/services/github/github-languages.service.js b/services/github/github-languages.service.js
index d204970d9d..077748fa8e 100644
--- a/services/github/github-languages.service.js
+++ b/services/github/github-languages.service.js
@@ -12,6 +12,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 class GithubCodeSize extends LegacyService {
   static get category() {
     return 'size'
diff --git a/services/github/github-last-commit.service.js b/services/github/github-last-commit.service.js
index a245aa4b1e..f5fe474a3e 100644
--- a/services/github/github-last-commit.service.js
+++ b/services/github/github-last-commit.service.js
@@ -12,6 +12,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubLastCommit extends LegacyService {
   static get category() {
     return 'activity'
diff --git a/services/github/github-license.service.js b/services/github/github-license.service.js
index ce8103ec2d..e89682a08f 100644
--- a/services/github/github-license.service.js
+++ b/services/github/github-license.service.js
@@ -12,6 +12,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubLicense extends LegacyService {
   static get category() {
     return 'license'
diff --git a/services/github/github-manifest-version.service.js b/services/github/github-manifest-version.service.js
index 6d3aebc181..cd905e4c43 100644
--- a/services/github/github-manifest-version.service.js
+++ b/services/github/github-manifest-version.service.js
@@ -12,6 +12,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubManifestVersion extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/github/github-release-date.service.js b/services/github/github-release-date.service.js
index 79b9c0f956..7250089035 100644
--- a/services/github/github-release-date.service.js
+++ b/services/github/github-release-date.service.js
@@ -10,6 +10,12 @@ const { formatDate } = require('../../lib/text-formatters')
 const { age } = require('../../lib/color-formatters')
 const { documentation } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubReleaseDate extends LegacyService {
   static get category() {
     return 'activity'
diff --git a/services/github/github-release.service.js b/services/github/github-release.service.js
index 608488bd50..7f95c2315e 100644
--- a/services/github/github-release.service.js
+++ b/services/github/github-release.service.js
@@ -11,6 +11,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubRelease extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/github/github-repo-size.service.js b/services/github/github-repo-size.service.js
index 089eced795..64527c78e7 100644
--- a/services/github/github-repo-size.service.js
+++ b/services/github/github-repo-size.service.js
@@ -11,6 +11,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubRepoSize extends LegacyService {
   static get category() {
     return 'size'
diff --git a/services/github/github-search.service.js b/services/github/github-search.service.js
index 4bb20fb473..ce4d895ee4 100644
--- a/services/github/github-search.service.js
+++ b/services/github/github-search.service.js
@@ -8,6 +8,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubSearch extends LegacyService {
   static get category() {
     return 'other'
diff --git a/services/github/github-size.service.js b/services/github/github-size.service.js
index 0b8dea75f3..d532d172bb 100644
--- a/services/github/github-size.service.js
+++ b/services/github/github-size.service.js
@@ -11,6 +11,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubSize extends LegacyService {
   static get category() {
     return 'size'
diff --git a/services/github/github-stars.service.js b/services/github/github-stars.service.js
index 8460957c74..8daaf2e125 100644
--- a/services/github/github-stars.service.js
+++ b/services/github/github-stars.service.js
@@ -11,6 +11,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubStars extends LegacyService {
   static get category() {
     return 'social'
diff --git a/services/github/github-tag.service.js b/services/github/github-tag.service.js
index f6644fb694..de64f50bd7 100644
--- a/services/github/github-tag.service.js
+++ b/services/github/github-tag.service.js
@@ -13,6 +13,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubTag extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/github/github-watchers.service.js b/services/github/github-watchers.service.js
index 7b7a178c30..52cee07e55 100644
--- a/services/github/github-watchers.service.js
+++ b/services/github/github-watchers.service.js
@@ -10,6 +10,12 @@ const {
   checkErrorResponse: githubCheckErrorResponse,
 } = require('./github-helpers')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class GithubWatchers extends LegacyService {
   static get category() {
     return 'social'
diff --git a/services/hackage/hackage-deps.service.js b/services/hackage/hackage-deps.service.js
index b886503da0..e851da4211 100644
--- a/services/hackage/hackage-deps.service.js
+++ b/services/hackage/hackage-deps.service.js
@@ -4,6 +4,12 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const { checkErrorResponse } = require('../../lib/error-helper')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class HackageDeps extends LegacyService {
   static get category() {
     return 'dependencies'
diff --git a/services/hackage/hackage-version.service.js b/services/hackage/hackage-version.service.js
index 4b1fb8bf6f..1d0ea6be4d 100644
--- a/services/hackage/hackage-version.service.js
+++ b/services/hackage/hackage-version.service.js
@@ -6,6 +6,12 @@ const { checkErrorResponse } = require('../../lib/error-helper')
 const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class HackageVersion extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/homebrew/homebrew.service.js b/services/homebrew/homebrew.service.js
index ddb94ab31f..ba3b8d2d0f 100644
--- a/services/homebrew/homebrew.service.js
+++ b/services/homebrew/homebrew.service.js
@@ -6,6 +6,12 @@ const { checkErrorResponse } = require('../../lib/error-helper')
 const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Homebrew extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/itunes/itunes.service.js b/services/itunes/itunes.service.js
index d2b5698e90..cc219bc089 100644
--- a/services/itunes/itunes.service.js
+++ b/services/itunes/itunes.service.js
@@ -5,6 +5,12 @@ const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Itunes extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/jenkins/jenkins-build.service.js b/services/jenkins/jenkins-build.service.js
index 310125edf5..76e71b3b79 100644
--- a/services/jenkins/jenkins-build.service.js
+++ b/services/jenkins/jenkins-build.service.js
@@ -4,6 +4,12 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const serverSecrets = require('../../lib/server-secrets')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class JenkinsBuild extends LegacyService {
   static get category() {
     return 'build'
diff --git a/services/jenkins/jenkins-plugin-version.service.js b/services/jenkins/jenkins-plugin-version.service.js
index 7fa3d96009..1579a6b9b2 100644
--- a/services/jenkins/jenkins-plugin-version.service.js
+++ b/services/jenkins/jenkins-plugin-version.service.js
@@ -6,6 +6,12 @@ const { regularUpdate } = require('../../lib/regular-update')
 const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class JenkinsPlugin extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/jenkins/jenkins-tests.service.js b/services/jenkins/jenkins-tests.service.js
index 159babd45d..061eb12f40 100644
--- a/services/jenkins/jenkins-tests.service.js
+++ b/services/jenkins/jenkins-tests.service.js
@@ -4,6 +4,12 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const serverSecrets = require('../../lib/server-secrets')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class JenkinsTests extends LegacyService {
   static get category() {
     return 'build'
diff --git a/services/jitpack/jitpack.service.js b/services/jitpack/jitpack.service.js
index 23926dda36..0a62b3ec6d 100644
--- a/services/jitpack/jitpack.service.js
+++ b/services/jitpack/jitpack.service.js
@@ -5,6 +5,12 @@ const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Jitpack extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/lgtm/lgtm-alerts.service.js b/services/lgtm/lgtm-alerts.service.js
index aeb6c62cae..6bbd35d12c 100644
--- a/services/lgtm/lgtm-alerts.service.js
+++ b/services/lgtm/lgtm-alerts.service.js
@@ -5,6 +5,12 @@ const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const { checkErrorResponse } = require('../../lib/error-helper')
 const { metric } = require('../../lib/text-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class LgtmAlerts extends LegacyService {
   static get category() {
     return 'quality'
diff --git a/services/lgtm/lgtm-grade.service.js b/services/lgtm/lgtm-grade.service.js
index 27815fb1ff..8c6e4010fb 100644
--- a/services/lgtm/lgtm-grade.service.js
+++ b/services/lgtm/lgtm-grade.service.js
@@ -4,6 +4,12 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const { checkErrorResponse } = require('../../lib/error-helper')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class LgtmGrade extends LegacyService {
   static get category() {
     return 'quality'
diff --git a/services/liberapay/liberapay.service.js b/services/liberapay/liberapay.service.js
index a278bf5673..fb38ee6fa6 100644
--- a/services/liberapay/liberapay.service.js
+++ b/services/liberapay/liberapay.service.js
@@ -6,6 +6,12 @@ const { metric } = require('../../lib/text-formatters')
 const { makeLogo: getLogo } = require('../../lib/badge-data')
 const { colorScale } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Liberapay extends LegacyService {
   static get category() {
     return 'funding'
diff --git a/services/librariesio/librariesio-dependencies.service.js b/services/librariesio/librariesio-dependencies.service.js
index e68a970d88..def778e5c3 100644
--- a/services/librariesio/librariesio-dependencies.service.js
+++ b/services/librariesio/librariesio-dependencies.service.js
@@ -4,6 +4,12 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const { checkErrorResponse } = require('../../lib/error-helper')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class LibrariesioDependencies extends LegacyService {
   static get category() {
     return 'dependencies'
diff --git a/services/luarocks/luarocks.service.js b/services/luarocks/luarocks.service.js
index ec87cf0c7c..63e74d1d10 100644
--- a/services/luarocks/luarocks.service.js
+++ b/services/luarocks/luarocks.service.js
@@ -8,6 +8,12 @@ const {
   compareVersionLists: luarocksCompareVersionLists,
 } = require('./luarocks-version')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Luarocks extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/maintenance/maintenance.service.js b/services/maintenance/maintenance.service.js
index c5dafb5fce..60147dc2d9 100644
--- a/services/maintenance/maintenance.service.js
+++ b/services/maintenance/maintenance.service.js
@@ -4,6 +4,12 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const log = require('../../lib/log')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Maintenance extends LegacyService {
   static get category() {
     return 'other'
diff --git a/services/maven-central/maven-central.service.js b/services/maven-central/maven-central.service.js
index 5c76ab21be..2539a33407 100644
--- a/services/maven-central/maven-central.service.js
+++ b/services/maven-central/maven-central.service.js
@@ -6,7 +6,12 @@ const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 
-// Based on repo1.maven.org rather than search.maven.org because of #846.
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class MavenCentral extends LegacyService {
   static get category() {
     return 'version'
@@ -39,6 +44,7 @@ module.exports = class MavenCentral extends LegacyService {
         const artifactId = match[2] // eg, `guice`
         const versionPrefix = match[3] || '' // eg, `1.`
         const format = match[4] || 'gif' // eg, `svg`
+        // Based on repo1.maven.org rather than search.maven.org because of #846.
         const metadataUrl = `${'http://repo1.maven.org/maven2' +
           '/'}${encodeURIComponent(groupId).replace(
           /\./g,
diff --git a/services/maven-metadata/maven-metadata.service.js b/services/maven-metadata/maven-metadata.service.js
index af27fae1a5..eb22f2acf7 100644
--- a/services/maven-metadata/maven-metadata.service.js
+++ b/services/maven-metadata/maven-metadata.service.js
@@ -6,6 +6,12 @@ const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class MavenMetadata extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/microbadger/microbadger.service.js b/services/microbadger/microbadger.service.js
index 19e90f90b9..db6dfbe598 100644
--- a/services/microbadger/microbadger.service.js
+++ b/services/microbadger/microbadger.service.js
@@ -7,6 +7,12 @@ const {
   makeLabel: getLabel,
 } = require('../../lib/badge-data')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class MicroBadger extends LegacyService {
   static get category() {
     return 'size'
diff --git a/services/nexus/nexus.service.js b/services/nexus/nexus.service.js
index eedb928941..1d2dcd7625 100644
--- a/services/nexus/nexus.service.js
+++ b/services/nexus/nexus.service.js
@@ -6,6 +6,12 @@ const { isSnapshotVersion: isNexusSnapshotVersion } = require('./nexus-version')
 const { addv: versionText } = require('../../lib/text-formatters')
 const { version: versionColor } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Nexus extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/osstracker/osstracker.service.js b/services/osstracker/osstracker.service.js
index f8eb61fe99..53aede7bba 100644
--- a/services/osstracker/osstracker.service.js
+++ b/services/osstracker/osstracker.service.js
@@ -5,6 +5,13 @@ const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const log = require('../../lib/log')
 
 // For NetflixOSS metadata: https://github.com/Netflix/osstracker
+//
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class OssTracker extends LegacyService {
   static get category() {
     return 'other'
diff --git a/services/packagecontrol/packagecontrol.service.js b/services/packagecontrol/packagecontrol.service.js
index 213a5304d3..4393e48f6f 100644
--- a/services/packagecontrol/packagecontrol.service.js
+++ b/services/packagecontrol/packagecontrol.service.js
@@ -7,6 +7,12 @@ const {
   downloadCount: downloadCountColor,
 } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class PackageControl extends LegacyService {
   static get category() {
     return 'downloads'
diff --git a/services/packagist/packagist-downloads.service.js b/services/packagist/packagist-downloads.service.js
index a69c02cc0d..0bb7a62dce 100644
--- a/services/packagist/packagist-downloads.service.js
+++ b/services/packagist/packagist-downloads.service.js
@@ -7,6 +7,12 @@ const {
   downloadCount: downloadCountColor,
 } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class PackagistDownloads extends LegacyService {
   static get category() {
     return 'downloads'
diff --git a/services/packagist/packagist-license.service.js b/services/packagist/packagist-license.service.js
index 1ef12fa9dd..3527c60c10 100644
--- a/services/packagist/packagist-license.service.js
+++ b/services/packagist/packagist-license.service.js
@@ -3,6 +3,12 @@
 const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class PackagistLicense extends LegacyService {
   static get category() {
     return 'license'
diff --git a/services/packagist/packagist-php-version.service.js b/services/packagist/packagist-php-version.service.js
index 33e91bb888..a70b76d4eb 100644
--- a/services/packagist/packagist-php-version.service.js
+++ b/services/packagist/packagist-php-version.service.js
@@ -4,6 +4,12 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const log = require('../../lib/log')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class PackagistPhpVersion extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/packagist/packagist-version.service.js b/services/packagist/packagist-version.service.js
index e4b6de2811..1ce130a0c9 100644
--- a/services/packagist/packagist-version.service.js
+++ b/services/packagist/packagist-version.service.js
@@ -10,6 +10,12 @@ const {
   isStable: phpStableVersion,
 } = require('../../lib/php-version')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class PackagistVersion extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/php-eye/php-eye-hhvm.service.js b/services/php-eye/php-eye-hhvm.service.js
index 0baa791d60..042028083d 100644
--- a/services/php-eye/php-eye-hhvm.service.js
+++ b/services/php-eye/php-eye-hhvm.service.js
@@ -7,6 +7,12 @@ const { omitv } = require('../../lib/text-formatters')
 
 const keywords = ['php', 'runtime']
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class PhpeyeHhvm extends LegacyService {
   static get category() {
     return 'platform-support'
diff --git a/services/php-eye/php-eye-php-version.service.js b/services/php-eye/php-eye-php-version.service.js
index 11d50b5319..a00672a298 100644
--- a/services/php-eye/php-eye-php-version.service.js
+++ b/services/php-eye/php-eye-php-version.service.js
@@ -8,6 +8,12 @@ const {
 } = require('../../lib/php-version')
 const log = require('../../lib/log')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class PhpEyePhpVersion extends LegacyService {
   static get category() {
     return 'platform-support'
diff --git a/services/pub/pub.service.js b/services/pub/pub.service.js
index 2c42b5154f..813bca4c25 100644
--- a/services/pub/pub.service.js
+++ b/services/pub/pub.service.js
@@ -7,6 +7,13 @@ const { version: versionColor } = require('../../lib/color-formatters')
 const { latest: latestVersion } = require('../../lib/version')
 
 // For Dart's pub.
+//
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Pub extends LegacyService {
   static get category() {
     return 'version'
diff --git a/services/puppetforge/puppetforge-modules.service.js b/services/puppetforge/puppetforge-modules.service.js
index f9d7967a11..9c958b3a78 100644
--- a/services/puppetforge/puppetforge-modules.service.js
+++ b/services/puppetforge/puppetforge-modules.service.js
@@ -104,6 +104,12 @@ class PuppetforgeModuleFeedback extends LegacyService {
   static registerLegacyRouteHandler() {}
 }
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 class PuppetforgeModules extends LegacyService {
   static registerLegacyRouteHandler({ camp, cache }) {
     camp.route(
diff --git a/services/puppetforge/puppetforge-users.service.js b/services/puppetforge/puppetforge-users.service.js
index 32304985e2..d23c198cef 100644
--- a/services/puppetforge/puppetforge-users.service.js
+++ b/services/puppetforge/puppetforge-users.service.js
@@ -54,6 +54,12 @@ class PuppetforgeUserModules extends LegacyService {
   static registerLegacyRouteHandler() {}
 }
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 class PuppetforgeUsers extends LegacyService {
   static registerLegacyRouteHandler({ camp, cache }) {
     camp.route(
diff --git a/services/scrutinizer/scrutinizer.service.js b/services/scrutinizer/scrutinizer.service.js
index f579b8bff7..a51cb48091 100644
--- a/services/scrutinizer/scrutinizer.service.js
+++ b/services/scrutinizer/scrutinizer.service.js
@@ -30,6 +30,12 @@ class ScrutinizerBuild extends LegacyService {
   static registerLegacyRouteHandler({ camp, cache }) {}
 }
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 class Scrutinizer extends LegacyService {
   static get category() {
     return 'quality'
diff --git a/services/sensiolabs/sensiolabs.service.js b/services/sensiolabs/sensiolabs.service.js
index d6f40b3eb9..5b3bab5cce 100644
--- a/services/sensiolabs/sensiolabs.service.js
+++ b/services/sensiolabs/sensiolabs.service.js
@@ -4,6 +4,12 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const serverSecrets = require('../../lib/server-secrets')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Sensiolabs extends LegacyService {
   static get category() {
     return 'build'
diff --git a/services/shippable/shippable.service.js b/services/shippable/shippable.service.js
index 6fad533cb2..6b9d80bb6f 100644
--- a/services/shippable/shippable.service.js
+++ b/services/shippable/shippable.service.js
@@ -4,6 +4,12 @@ const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 const { checkErrorResponse } = require('../../lib/error-helper')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Shippable extends LegacyService {
   static get category() {
     return 'build'
diff --git a/services/sonarqube/sonarqube.service.js b/services/sonarqube/sonarqube.service.js
index 37212ea61a..a863b50812 100644
--- a/services/sonarqube/sonarqube.service.js
+++ b/services/sonarqube/sonarqube.service.js
@@ -8,6 +8,12 @@ const {
   coveragePercentage: coveragePercentageColor,
 } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Sonarqube extends LegacyService {
   static get category() {
     return 'quality'
diff --git a/services/sourceforge/sourceforge.service.js b/services/sourceforge/sourceforge.service.js
index fa9ad2e77c..d06e851fee 100644
--- a/services/sourceforge/sourceforge.service.js
+++ b/services/sourceforge/sourceforge.service.js
@@ -11,6 +11,12 @@ const {
   downloadCount: downloadCountColor,
 } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Sourceforge extends LegacyService {
   static get category() {
     return 'downloads'
diff --git a/services/teamcity/teamcity-build.service.js b/services/teamcity/teamcity-build.service.js
index 947ae20e8d..1b252776a6 100644
--- a/services/teamcity/teamcity-build.service.js
+++ b/services/teamcity/teamcity-build.service.js
@@ -3,6 +3,12 @@
 const LegacyService = require('../legacy-service')
 const { makeBadgeData: getBadgeData } = require('../../lib/badge-data')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 function teamcityBadge(
   url,
   buildId,
diff --git a/services/teamcity/teamcity-coverage.service.js b/services/teamcity/teamcity-coverage.service.js
index 72ffe81556..19b78d082e 100644
--- a/services/teamcity/teamcity-coverage.service.js
+++ b/services/teamcity/teamcity-coverage.service.js
@@ -6,6 +6,12 @@ const {
   coveragePercentage: coveragePercentageColor,
 } = require('../../lib/color-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class TeamcityCoverage extends LegacyService {
   static get category() {
     return 'quality'
diff --git a/services/travis/travis-build.service.js b/services/travis/travis-build.service.js
index 78dec2ff9d..f4f872efe5 100644
--- a/services/travis/travis-build.service.js
+++ b/services/travis/travis-build.service.js
@@ -6,6 +6,13 @@ const { checkErrorResponse } = require('../../lib/error-helper')
 const log = require('../../lib/log')
 
 // Handle .org and .com.
+//
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class TravisBuild extends LegacyService {
   static get category() {
     return 'build'
diff --git a/services/travis/travis-php-version.service.js b/services/travis/travis-php-version.service.js
index 4c23fa47fd..6ca312d93c 100644
--- a/services/travis/travis-php-version.service.js
+++ b/services/travis/travis-php-version.service.js
@@ -9,6 +9,12 @@ const {
   getPhpReleases,
 } = require('../../lib/php-version')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class TravisPhpVersion extends LegacyService {
   static get category() {
     return 'platform-support'
diff --git a/services/twitter/twitter.service.js b/services/twitter/twitter.service.js
index 76244884ee..70fba96811 100644
--- a/services/twitter/twitter.service.js
+++ b/services/twitter/twitter.service.js
@@ -7,6 +7,12 @@ const {
 } = require('../../lib/badge-data')
 const { metric } = require('../../lib/text-formatters')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 class TwitterUrl extends LegacyService {
   static get category() {
     return 'social'
@@ -55,6 +61,12 @@ class TwitterUrl extends LegacyService {
   }
 }
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 class TwitterFollow extends LegacyService {
   static get category() {
     return 'social'
diff --git a/services/vaadin-directory/vaadin-directory.service.js b/services/vaadin-directory/vaadin-directory.service.js
index 3c47841cba..b7bbb003de 100644
--- a/services/vaadin-directory/vaadin-directory.service.js
+++ b/services/vaadin-directory/vaadin-directory.service.js
@@ -169,6 +169,12 @@ class VaadinDirectoryReleaseDate extends LegacyService {
   static registerLegacyRouteHandler() {}
 }
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 class VaadinDirectory extends LegacyService {
   static registerLegacyRouteHandler({ camp, cache }) {
     camp.route(
diff --git a/services/vscode-marketplace/vscode-marketplace.service.js b/services/vscode-marketplace/vscode-marketplace.service.js
index 519ca67b26..07a8d6400b 100644
--- a/services/vscode-marketplace/vscode-marketplace.service.js
+++ b/services/vscode-marketplace/vscode-marketplace.service.js
@@ -1,5 +1,12 @@
 'use strict'
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
+
 const LegacyService = require('../legacy-service')
 const {
   makeBadgeData: getBadgeData,
diff --git a/services/waffle/waffle.service.js b/services/waffle/waffle.service.js
index 2cfec099af..4cf2e2270c 100644
--- a/services/waffle/waffle.service.js
+++ b/services/waffle/waffle.service.js
@@ -8,6 +8,12 @@ const {
 } = require('../../lib/badge-data')
 const { checkErrorResponse } = require('../../lib/error-helper')
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Waffle extends LegacyService {
   static get category() {
     return 'issue-tracking'
diff --git a/services/website/website.service.js b/services/website/website.service.js
index 20172f3682..142be209cc 100644
--- a/services/website/website.service.js
+++ b/services/website/website.service.js
@@ -69,6 +69,12 @@ const documentation = `
 </p>
 `
 
+// This legacy service should be rewritten to use e.g. BaseJsonService.
+//
+// Tips for rewriting:
+// https://github.com/badges/shields/blob/master/doc/rewriting-services.md
+//
+// Do not base new services on this code.
 module.exports = class Website extends LegacyService {
   static get category() {
     return 'monitoring'
-- 
GitLab