Project

General

Profile

Manual de uso

Convenciones usadas en el manual

Para sustentar el manual, cabe definir una serie de convenciones que nos permitan trabajar con los ejemplos.
Esas convenciones estarán aplicadas en los ejemplos y en las configuraciones por defecto de las herramientas.
En caso de que una organización no tenga definidas sus convenciones o sus procedimientos, se recomienda usar éstas hasta haber podido definir sus propias necesidades.

Clases: Requisitos (Req) y documentos de requisitos (ReqDoc).

Normalmente un proyecto agrupa sus requisitos en documentos. En la base de datos de requisitos esto se consigue definiendo unos elementos de clase ReqDoc, a los que llamaremos "documentos de requisitos", que agrupan los requisitos. Estos elementos suelen actuar como raíces dentro del árbol de requisitos del proyecto, aunque también pueden ser hijos de otros ReqDoc. Estos elementos cumplen dos funciones principales:
  • Cuando se realiza una exportación a hoja de cálculo, a Doorstop o a informes, estos elementos se convierten en documentos “reales” dentro de los cuales se agrupan los requisitos. En el caso de la exportación a hoja de cálculo, los ReqDoc se muestran como pestañas dentro de las cuales se encuentran como filas los requisitos que éstos engloban.
  • Establecen un prefijo para los identificadores de requisitos (RqID), de forma que los identificadores todos los requisitos agrupados en su interior usan ese prefijo como raíz.

Anatomía de un requisito

Un requisito en cosmoSys-Req consta, como mínimo de:

  • Id: Un identificador de la base de datos (numérico). En algunas vistas en forma de tabla se denota con el símbolo #
  • RqTitle: Título del requisito. Un texto corto para referirnos a él. No es el requisito en sí.
  • RqID: Un identificador de requisito dentro del documento (alfanumérico).
  • Parent: Relación con un requisito padre. Esta relación nos permite construir la base de datos de requisitos como un árbol de documento, para poder dotar de legibilidad al documento de requisitos cuando éste se genere.
  • Related requirements: Relaciones (cardinalidad N : N) de dependencia entre requisitos.
  • Description: El texto con los requisitos (el requisito en sí mismo). Debería seguir una nomenclatura convencional del tipo “the system shall ----- ”, y cumplir las características exigibles a los requisitos (no ambiguo, necesario, demostrable, etc.).
  • RqRationale: Un texto razonando el por qué del requisito o la estrategia seguida para poner el requisito de la manera que se ha puesto. Este campo suele quedar siempre oculto para las entidades externas a la institución que elabora los requisitos. Por defecto, su valor es {TODO}.

Según nuestra convención, un requisito tiene, además, los siguientes atributos:

  • RqLevel: Nivel del requisito.
    • None: valor por defecto : Al requisito aún no se ha asignado un nivel.
    • System: El requisito está definido a nivel de sistema, es decir.
    • Derived: El requisito ha sido derivado desde un requisito complejo (RqType = Complex).
    • External: El requisito no pertenece al sistema que se está especificando, sino a otro sistema de su entorno. Este requisito se añade al documento de requisitos ya que modela una imposición (restricción, característica a ser tenida en cuenta, condición de interfaz) hacia el sistema en definición y, por tanto, será origen de las relaciones de dependencia de los requisitos afectados por dicha imposición.
    • Shared: El requisito no pertenece en exclusiva al sistema que se está especificando, sino al supersistema al que pertenece. Este requisito se añade al documento de requisitos ya que modela unas condiciones de contorno para que el sistema que se define colabore en satisfacer dicho requisito y, por tanto, será origen de las relaciones de dependencia de los requisitos de sistema implicados en dicha colarboración. Suele complementarse con requisitos del tipo External que explican las funciones a cubrir por los otros sistemas que colaboran en satisfacer el requisito del suprasistema.
  • RqType: Tipo de requisito.
    • Info: valor por defecto : No es un requisito real, sólo se usa con carácter informativo para poder dotar de legibilidad al documento de requisitos cuando éste se genere. Los requisitos que actúan como padres de otros requisitos son del tipo Info.
    • Complex: El requisito es complejo, no atómico, y se considera que no puede ser implementado usando una única disciplina (Hw / Sw / Opt / Mech). Para poder ser implementado, a partir de estos requisitos deben derivarse otros requisitos atómicos cuya cooperación garantice el cumplimiento del requisito complejo. Los requisitos derivados (RqLevel = Derived) deberán estar enlazados de forma que dependan del requisito complejo. También son requisitos complejos aquellos cuyo nivel no quede contenido en el sistema que se define (RqLevel = External o Shared).
    • Hw: Requisitos no complejos implementables usando la disciplina Hw (electrónica).
    • Sw: Requisitos no complejos implementables usando la disciplina Sw (informática).
    • Opt: Requisitos no complejos implementables usando la disciplina Opt (óptica).
    • Mech: Requisitos no complejos implementables usando la disciplina Mech (mecánica).
  • RqSources: Fuentes de requisitos. Texto conteniendo, separados por comas, identificadores de documentos que introduzcan la necesidad del requisito, aporten restricciones, o condicionen su redacción. Muy comúnmente, el campo RqRazones suele hacer mención a estas fuentes.
  • RqChapter: Cadena de caracteres que posibilita que, al ordenar los requisitos según este valor, el documento de requisitos queda legible.
  • RqTarget: Especifica la iteración de desarrollo para la cual se planifica ese requisito.

Los siguientes atributos son opcionales, y están pensados para facilitar la integración de las herramientas con otros sistemas de gestión (como por ejemplo para sustentar una validación de la arquitectura propuesta para el sistema contra los requisitos del sistema).

  • RqValue: Texto en el que el ingeniero puede destacar un valor relacionado con el requisito (típicamente el valor central del requisito). El formato es textual y en ese texto se puede usar cualquier tipo de sintaxis. Por ejemplo, imaginemos que el requisito es “el sistema deberá disparar una alarma cuando la temperatura ambiente sea mayor o igual a 5ºC +/- 0,1ºC: El campo RqValue podría contener “5ºC +/- 0,1ºC”. Es muy importante garantizar que el valor que se encuentra en éste campo es el mismo que el que se encuentra en la descripción del documento. En el futuro, la herramienta dispondrá de un mecanismo para asegurar que el valor sólo se encuentra definida en el campo RqValue, y que la descripción textual consumirá esa definición para mostrarse.
  • RqVar: Identificador por el que se conoce al valor definido en el presente requisito, aparte del identificador propio de Redmine o de la Bd de requsitos. Un ejemplo puede ser AlarmTemp para definir la temperatura de disparo de una alarma. Usado en conjunción con RqValue se puede construir la frase RqVar = RqValue, y se puede hacer referencia a esa variable en la documentación en vez del valor literal que toma esa variable en un momento dado. Haciendo descansar el texto del requisito (la descripción) sobre la variable especificada en RqVar (al estilo “el sistema deberá disparar una alarma cuando la temperatura ambiente sea mayor o igual a AlarmTemp”, se consigue que el valor literal descanse sólo en el campo RqValue, y no aparezca dos veces en el requisito.

Estados de un requisito

Los documentos de requisitos deben ser aprobados para que los diseñadores puedan trabajar en la solución (arquitectura, plan de validación, ...). Para estar aprobados deben haber sido redactados y revisados, y el revisor debe haber aprobado su contenido. En el momento en el que un requisito aprobado sufre el más mínimo cambio en su redacción, el requisito debería perder su estado de “aprobado” y volver a considerarse en redacción. Se establece la siguiente convención relativa a los estados de los requisitos. Redmine utilizará esta convención para controlar cómo los requisitos evolucionan o cambian. Para cada requisito, establecemos un nivel de “madurez” que nos permite saber qué cambios de estado desembocan en una pérdida de madurez. Como regla general podemos decir que un cambio dentro del mismo nivel de madurez no implica la necesidad de que un revisor entre en juego.

  • RqDraft: Madurez 1. valor por defecto El requisito se encuentra siendo redactado.
  • RqStable: Madurez 2. El requisito se considera estable, ha acabado su redacción, y se encuentra esperando ser revisado.
  • RqApproved: Madurez 3. El requisito ha sido revisado y se considera aprobado.
  • RqIncluded: Madurez 3. El requisito estaba aprobado (RqApproved) y, además, se ha incluído su implementación en el sistema (o en el “artefacto de desarrollo” usando la nomenclatura agile modeling).
  • RqValidated: Madurez 3. El requisito estaba incluído (RqIncluded) y, además, la última prueba de validación que se hizo contra ese requisito arrojó resultado positivo.
  • RqRejected: Madurez 0. El requisito ha sido revisado y se considera rechazado.
  • RqErased: Madurez -1. El requisito se ha eliminado del sistema, y sólo continúa presente por consistencia con el histórico de la base de datos de requisitos.
  • RqZombie: Madurez 0. El requisito se ha eliminado del sistema temporalmente, para que no sea tenido en cuenta por el proceso de gestión de requisitos, pero se estima que pueda volver al proceso en el futuro, razón por la que no se le ha otorgado el estado RqErased.

En la imagen, las transiciones posibles entre estados. En cada transición aparecen los roles que las pueden ejecutar.

Roles en la gestion de requisitos:

  • RqManager: Permite configurar un equipo de gestores de requisitos, otorgando roles a los miembros del equipo, y configurando los datos del proyecto.
  • RqWriter: Escribe los requisitos en modo RqDraft, y los eleva a RqStable cuando los considera listos para revisión. Puede también hacer cambios estructurales en la base de datos de requisitos del proyecto. También puede pasar un requisito a RqErased o RqZombie.
  • RqReviewer: Revisor de requisitos. Revisa los requisitos en estado RqStable y los pasa a RqAprproved o RqRejected.
  • Developer: Asigna los requisitos a alguna iteración del desarrollo, y los marca como RqIncluded cuando se ha desarrollado la capacidad del sistema (o artefacto) de satisfacer el requisito.
  • Tester: Cuando una prueba de validación se ejecuta correctamente, puede pasar los requisitos a RqValidated si la prueba ha ido mal. En caso de que la prueba de un requisito RqValidated falle, puede pasar el requisito a RqIncluded de nuevo.

Avance de los requisitos y del proyecto

Los requisitos (independientemente de su estado) se asignan a alguna iteración de desarrollo, de esta forma quedan planificadas. Los revisores pueden revisar los requisitos en cuanto éstos se encuentren en el estado “Estable”, aunque deberían priorizar la aprobación de aquellos requisitos cuya planificación los haya asignado a iteraciones más próximas en el tiempo. Para poder cerrar la especificación de una iteración, todos los requisitos cuyo RqTarget sea esa iteración o cualquiera de las anteriores dentro del plan de iteraciones, deberá encontrarse en estado “aprobado”. Un documento generado filtrando sólo aquellos requisitos de la iteración actual y las anteriores debe ser legible, entendible, ser completo, y estar aprobado en su totalidad. En ocasiones, para lograr una especificación consistente del sistema para una iteración, se puede necesitar escribir (y aprobar) requisitos temporales. Se considera que un sistema se puede entregar si todos sus requisitos están en RqValidated, y se considera que se puede abordar la validación completa del sistema una vez que todos los requisitos estén en estado RqIncluded.

¿Requisitos temporales?

Existen ocasiones en las que tiene sentido definir de manera temporal un requisito, implementable a esa altura del desarrollo, para que sustituya temporalmente a otro cuya redacción no sería imposible cerrar (o implementar) en ese momento.

Un ejemplo es la creación de una versión “autoespecificada”, “degradada” o “relajada” de un requisito para permitir al sistema que implememente la satisfacción de un grupo de requisitos que dependerían de él.

Imaginemos una funcionalidad de comunicaciones especificada según los requisitos V,W,Z, que dependen de otro requisito R, donde se encuentra un identificador de comunicaciones que debe definir el cliente, pero que no lo definirá hasta cerrar toda la mensajería del suprasistema, casi al final de la etapa del desarrollo. El requisito R no podrá pasar a estable, por lo que no podrá revisarse y aprobarse, por lo que no podrá implementarse. Los requisitos V,W,Z, que dependen de él, tampoco podrán aprobarse. En realidad toda la funcionalidad podría implementarse, e incluso validarse a un 99% utilizando cualquier otro identificador, temporalmente, que sería sustituido por el identificador final una vez el requisito R pueda escribirse (cuando el cliente aporte el dato). Para evitar poner un dato temporal en un requisito estable, aprobado, etc. se crea un requisito “autoespecificado” R2, que sustituye a R durante las siguientes iteraciones de desarrollo, y se deja R para más adelante. R2 (cuya validez es temporal) se integra con V,W,Z sustituyendo a R, y permite que los demás requisitos se aprueben, satisfagan y validen. Cuando más adelante se sustituya R2 por R, los requisitos V,W,Z volverán a necesitar ser revisados y aprobados, como también deberá ser actualizada la implementación y re-ejecutada la validación, garantizando que el identificador correcto llega a producción. El coste de volver a ejecutar este flujo de gestión de requisitos por segunda vez es mínimo, teniendo en cuenta que el trabajo que requiere más esfuerzo (la revisión de los requisitos y el desarrollo del sistema que los satisface) ya se ha adelantado en un 99%, y que la única tarea a repetir es la reejecución de la validación.

R2 pasaría al estado RqErased, sin dependencias sobre ningún otro requisito, una vez cumplida su función.

Un recorrido por el proyecto de ejemplo

Se recomienda ejecutar el recorrido por el proyecto de ejemplo para poder ver en funcionamiento la herramienta.

Casos de uso

Los casos de uso de la herramienta de requisitos son los siguientes:

Describir cómo se ejecuta cada uno de estos casos de uso.

Adicionalmente, el personal de administración y/o mantenimiento de la herramienta tiene a su disposición los siguientes casos de uso: