Gestión de versiones

Con DeveloperHub, puede crear versiones de su documentación. La versión predeterminada se llama v1.0, y usted decide cómo nombrar sus versiones. No es obligatorio usar versionado semántico, por lo que puede usar palabras como "beta", "alpha" y "latest" junto con números de versión reales.

El versionado es muy potente. Cuando las páginas están enlazadas dentro de una versión y esa versión se clona, todos los enlaces de las páginas se actualizan para que coincidan con la nueva versión.

Gestionar versiones

La mayoría de las acciones de versión están en la página Manage Versions. Para abrirla:

  • En la navegación superior del editor, haga clic en el menú de versiones.

  • Haga clic en el engranaje de ajustes .

La lista de la izquierda muestra todas las versiones del proyecto. Seleccione una versión para ver y editar su configuración a la derecha.

Crear versiones

Para crear una nueva versión:

  1. Abra el menú de versiones en la navegación superior.

  2. Haga clic en + New version.

  3. Asígnele un nombre.

  4. Elija Clone from current version para copiar toda la documentación y las páginas de la versión actual, o Create from scratch para empezar vacía.

¿Qué ha ocurrido?

Al clonar una versión, toda la documentación, referencia de API y páginas de la versión de origen se copian a la nueva versión.

Clonar mediante la API

También puede clonar una versión mediante la API, lo cual es útil para crear una nueva versión desde un flujo de publicación. Copia el mismo contenido que el editor y deja la nueva versión sin publicar, para que pueda revisarla antes de que se publique. La clave de API necesita el permiso version.edit.

Publicar el clon es una llamada aparte que requiere el permiso version.publish. Todo lo que hay dentro de una versión clonada empieza sin publicar, así que publique primero una documentación o una referencia de API en ella; de lo contrario, se rechazará la publicación de la versión.

Copiar páginas a otra versión

Cuando se escriben páginas después de crear una versión, puede copiarlas a esa versión en lugar de volver a crearlas.

  1. En el índice, haga clic en el menú de la página que desea copiar y elija Move. Para copiar varias, selecciónelas primero. Todo lo que hay bajo una página o categoría se copia con ella.

  2. Elija la Version y la Section de destino.

  3. Elija Copy y confirme.

Las copias conservan su estado de publicación, así que una página publicada aquí también estará publicada en la otra versión.

Si ya existe una página con el mismo slug en esa sección, elija qué ocurre con ella:

  • Replace: sobrescribe su contenido con la copia. Su historial conserva lo que decía antes.

  • Skip: se deja como está. Las páginas que dependen de ella se copian igualmente.

  • Keep both: añade la copia junto a ella, con una nueva URL.

Para mover las páginas en lugar de copiarlas, elija Move en lugar de Copy.

Si las copias enlazan a páginas que la otra versión no tiene, se le indicará cuántas, para que pueda comprobar los enlaces rotos de esa versión.

Para copiar una sección completa de documentación, consulte Copiar documentación a una versión.

Publicar versiones

De forma predeterminada, las versiones no están publicadas. Para publicar (o despublicar):

  • Abra el menú de versiones en la navegación superior y seleccione la versión.

  • En Manage Versions, active Published en la tarjeta Visibility o use el botón Publish / Unpublish del encabezado.

Cuando se publica una versión, los lectores solo podrán ver la documentación y las referencias de API publicadas de esa versión. Despublicar una versión hace que la versión y todo su contenido dejen de ser visibles para los lectores, pero no modifica el estado de publicación de su documentación y referencias de API.

Las versiones sin publicar muestran una etiqueta Unpublished en el menú de versiones y en la lista de Manage Versions.

Eliminar versiones

Para eliminar una versión:

  1. Abra Manage Versions.

  2. Seleccione la versión que desea eliminar.

  3. En la tarjeta Danger zone, haga clic en Delete version.

  4. Confirme la eliminación.

Advertencia

Una vez eliminada una versión, no se puede recuperar.

Ordenar versiones

Para cambiar el orden de una versión en el selector:

  • Abra Manage Versions.

  • Arrastre la versión desde el control .

  • Suelte la versión en el lugar deseado.

Si la versión está en primer lugar y está publicada, será la versión predeterminada que se cargue para sus lectores.

La versión predeterminada no muestra su slug en los enlaces de las páginas publicadas; por ejemplo, si la versión 1.0 fuera la predeterminada de este proyecto de documentación:

https://docs.developerhub.io/support-center/managing-versions significaría implícitamente que debe cargarse la versión predeterminada, que es la versión 1.0. Usar https://docs.developerhub.io/v1.0/support-center/managing-versions daría el mismo resultado.

Ocultar el selector de versiones

Si su proyecto solo tiene una versión, o prefiere que los lectores no cambien de versión por sí mismos, puede quitar el menú desplegable de versiones de la navegación superior del lector.

Para ocultarlo:

  • Abra Project Settings y luego el panel Customisation.

  • En la tarjeta Look and feel, active Hide version picker.

La vista previa del lector en la parte superior del panel se actualiza al activar la opción, así que puede ver la navegación superior sin el selector antes de guardar.

Ocultar el selector solo elimina el menú desplegable. Las versiones no se modifican: su estado de publicación se mantiene y los lectores aún pueden abrir cualquier versión publicada mediante un enlace que incluya su slug, como https://docs.developerhub.io/v1.0/support-center/managing-versions.

Mover a los lectores a la nueva versión

Si sus lectores han guardado como marcadores páginas de versiones antiguas, o no saben que su documentación tiene versiones, quizá quiera avisarles con un banner en la parte superior de la página de que hay una versión más reciente. Puede hacerlo mediante un ajuste avanzado estableciendo warnings.oldVersion en true.

Banner que sugiere al lector que hay una versión más reciente

Bloquear versiones

Las versiones se pueden bloquear cuando ya no deba poder editarse su documentación ni sus referencias de API. Cuando una versión está bloqueada, la documentación y las referencias de API no pueden ser:

  • Creadas.

  • Editadas.

  • Eliminadas.

  • Publicadas.

Esto también se aplica a los cambios realizados mediante la API.

Para bloquear o desbloquear una versión:

  • Abra Manage Versions.

  • Seleccione la versión.

  • En la tarjeta Visibility, active Locked.

Una etiqueta Locked aparece en el menú de versiones y en la lista de Manage Versions. Los botones Save draft y Publish de las páginas se sustituyen por un botón "Locked" desactivado.

Informes de versión

Se pueden descargar informes de versión que incluyen una lista de todas las páginas con la siguiente información:

  • Título

  • Creador

  • Actualizador

  • Fecha de creación

  • Fecha de actualización

  • Está en borrador

  • Está publicada

Para descargar un informe de versión:

  • Abra Manage Versions.

  • Seleccione la versión.

  • En la tarjeta Lifecycle, haga clic en Download junto a Pages report.


  Última actualización