diff --git a/services/amo/amo.service.js b/services/amo/amo.service.js
index da123461f6f74..0c2822c3be84e 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 5ef5db57d9522..1862b36feeaa8 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 874fba7375f00..0c6a1242eddcd 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 4d88b7ffe9579..b3cbe261fdfab 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 9987b4b9f690d..209e7b99c4697 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 ec4e8b7249e69..077ab09c73513 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 627f814b19fd1..f51cb41392df5 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 ba0bb8d3811e0..164f7c5f0e0a5 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 1a1e748cdd4c5..916e20a8fe9d3 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 f4e63588f691d..2d21098ade537 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 2a3d71061ebd9..80387e5da15f2 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 2c9c0e63ea162..f9fcdfc1a9ae9 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 c8fff7913cf24..147e0f347ec10 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 e7f7b9483ce62..27d05ea26254f 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 91c6865970f1b..50b7cdc1b61da 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 7db76356dcf87..e1e884f923b16 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 f6c2528aa464f..5ab44ad6db767 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 b0556ba7960e1..e745e864f2d46 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 ac27e30865fdf..3d221d541c962 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/cpan/cpan.service.js b/services/cpan/cpan.service.js
index e2e97eaa4dde5..7b265fda950fa 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 ce41521058ed1..5ae15c5e96379 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 4d9e079933d76..d2b867556e4b0 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 c92fb65039ab3..0b76d6b99c04c 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 5c0c8967f1765..587db9f487065 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 11dd3e27427c3..2c2bef12fcb80 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 0838f2962df25..7001345a88a8f 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 b2ef6f069de28..1f064a2ab0ff6 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 aa184a7dc7f4d..3e48157c93e02 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 3b7bbbacaaa9c..15b1808d1701b 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 a813d8e9e184b..de996ee14e12e 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 d7800820a303e..cb4dae45f0a4b 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 fbbddb0b331e3..65c6e82af328a 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 475b9012d470b..adc7d9c42e1cf 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 d204970d9d93d..077748fa8e593 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 a245aa4b1ecf2..f5fe474a3ef25 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 ce8103ec2d7b6..e89682a08f0f2 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 6d3aebc181059..cd905e4c43030 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 79b9c0f956f3e..7250089035f4f 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 608488bd509ef..7f95c2315e28e 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 089eced795658..64527c78e75f9 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 4bb20fb473390..ce4d895ee4b84 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 0b8dea75f3db0..d532d172bb006 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 8460957c74b7a..8daaf2e1259da 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 f6644fb694e07..de64f50bd7c1f 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 7b7a178c30b31..52cee07e552f6 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 b886503da0f90..e851da42115f3 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 4b1fb8bf6f71d..1d0ea6be4d19c 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 ddb94ab31f289..ba3b8d2d0f30f 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 d2b5698e90d53..cc219bc08903e 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 310125edf5e77..76e71b3b793d4 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 7fa3d96009a74..1579a6b9b29e9 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 159babd45df03..061eb12f400b5 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 23926dda36e18..0a62b3ec6d321 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 aeb6c62caeedf..6bbd35d12c6ab 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 27815fb1ff8f8..8c6e4010fb2eb 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 a278bf567371f..fb38ee6fa639b 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 e68a970d88155..def778e5c338f 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 ec87cf0c7c85b..63e74d1d10eee 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 c5dafb5fce4c1..60147dc2d9e3c 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 5c76ab21becf5..2539a334075f5 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 af27fae1a5f42..eb22f2acf7f61 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 19e90f90b9bc8..db6dfbe598ab7 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 eedb928941ca2..1d2dcd76250d5 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 f8eb61fe99c94..53aede7bbae83 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 213a5304d37e0..4393e48f6f403 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 a69c02cc0d97f..0bb7a62dce8e1 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 1ef12fa9dd9f9..3527c60c10284 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 33e91bb888ed8..a70b76d4ebde4 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 e4b6de281136f..1ce130a0c9481 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 0baa791d609fd..042028083d1a1 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 11d50b5319201..a00672a2989bd 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 2c42b5154f4f1..813bca4c25f4e 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 f9d7967a11b1f..9c958b3a7834a 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 32304985e2fc6..d23c198cef4ab 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 f579b8bff704d..a51cb48091f8f 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 d6f40b3eb9805..5b3bab5cce473 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 6fad533cb298d..6b9d80bb6f24f 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 37212ea61acdd..a863b50812238 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 fa9ad2e77c496..d06e851feeae2 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 947ae20e8daa3..1b252776a6938 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 72ffe81556497..19b78d082e359 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 78dec2ff9dc80..f4f872efe5113 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 4c23fa47fd0b3..6ca312d93cf70 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 76244884ee58a..70fba968115d5 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 3c47841cba626..b7bbb003dede0 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 519ca67b2651d..07a8d6400bc20 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 2cfec099af087..4cf2e2270c8b0 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 20172f3682a23..142be209cc8a9 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'