Fix variable naming for [ROS] version service (#8292)

* Fix variable naming for [ROS] version service

* Add documentation

* use noetic instead of galactic in example

Co-authored-by: repo-ranger[bot] <39074581+repo-ranger[bot]@users.noreply.github.com>

services/ros/ros-version.service.js

@@ -34,31 +34,43 @@ const contentSchema = Joi.object({
 const distroSchema = Joi.object({
   repositories: Joi.object().required(),
 })
-const packageSchema = Joi.object({
+const repoSchema = Joi.object({
   release: Joi.object({
     version: Joi.string().required(),
   }).required(),
 })
 
+const documentation = `
+<p>
+  To use this badge, specify the ROS <a href="http://docs.ros.org">distribution</a>
+  (e.g. <code>noetic</code> or <code>humble</code>) and the package repository name
+  (in the case of single-package repos, this may be the same as the package name).
+  This badge determines which versions are part of an official ROS distribution by
+  fetching from the <a href="https://github.com/ros/rosdistro">rosdistro</a> YAML files,
+  at the tag corresponding to the latest release.
+</p>
+`
+
 export default class RosVersion extends GithubAuthV4Service {
   static category = 'version'
 
-  static route = { base: 'ros/v', pattern: ':distro/:packageName' }
+  static route = { base: 'ros/v', pattern: ':distro/:repoName' }
 
   static examples = [
     {
       title: 'ROS Package Index',
-      namedParams: { distro: 'humble', packageName: 'vision_msgs' },
+      namedParams: { distro: 'humble', repoName: 'vision_msgs' },
       staticPreview: {
         ...renderVersionBadge({ version: '4.0.0' }),
         label: 'ros | humble',
       },
+      documentation,
     },
   ]
 
   static defaultBadgeData = { label: 'ros' }
 
-  async handle({ distro, packageName }) {
+  async handle({ distro, repoName }) {
     const tagsJson = await this._requestGraphql({
       query: gql`
         query ($refPrefix: String!) {
@@ -116,13 +128,13 @@ export default class RosVersion extends GithubAuthV4Service {
     }
     const version = this.constructor._parseReleaseVersionFromDistro(
       contentJson.data.repository.object.text,
-      packageName
+      repoName
     )
 
     return { ...renderVersionBadge({ version }), label: `ros | ${distro}` }
   }
 
-  static _parseReleaseVersionFromDistro(distroYaml, packageName) {
+  static _parseReleaseVersionFromDistro(distroYaml, repoName) {
     let distro
     try {
       distro = yaml.load(distroYaml)
@@ -136,19 +148,19 @@ export default class RosVersion extends GithubAuthV4Service {
     const validatedDistro = this._validate(distro, distroSchema, {
       prettyErrorMessage: 'invalid distribution.yml',
     })
-    if (!validatedDistro.repositories[packageName]) {
-      throw new NotFound({ prettyMessage: `package not found: ${packageName}` })
+    if (!validatedDistro.repositories[repoName]) {
+      throw new NotFound({ prettyMessage: `repo not found: ${repoName}` })
     }
 
-    const packageInfo = this._validate(
-      validatedDistro.repositories[packageName],
-      packageSchema,
+    const repoInfo = this._validate(
+      validatedDistro.repositories[repoName],
+      repoSchema,
       {
-        prettyErrorMessage: `invalid section for ${packageName} in distribution.yml`,
+        prettyErrorMessage: `invalid section for ${repoName} in distribution.yml`,
       }
     )
 
     // Strip off "release inc" suffix
-    return packageInfo.release.version.replace(/-\d+$/, '')
+    return repoInfo.release.version.replace(/-\d+$/, '')
   }
 }

services/ros/ros-version.tester.js

@@ -3,20 +3,20 @@ import { createServiceTester } from '../tester.js'
 
 export const t = await createServiceTester()
 
-t.create('gets the package version of vision_msgs in active distro')
+t.create('gets the version of vision_msgs in active distro')
   .get('/humble/vision_msgs.json')
   .expectBadge({ label: 'ros | humble', message: isSemver })
 
-t.create('gets the package version of vision_msgs in EOL distro')
+t.create('gets the version of vision_msgs in EOL distro')
   .get('/lunar/vision_msgs.json')
   .expectBadge({ label: 'ros | lunar', message: isSemver })
 
-t.create('returns not found for invalid package')
-  .get('/humble/this package does not exist - ros test.json')
+t.create('returns not found for invalid repo')
+  .get('/humble/this repo does not exist - ros test.json')
   .expectBadge({
     label: 'ros',
     color: 'red',
-    message: 'package not found: this package does not exist - ros test',
+    message: 'repo not found: this repo does not exist - ros test',
   })
 
 t.create('returns error for invalid distro')