Merged in docs/agregar-documentacion-comandos (pull request #32)

docs: agregar documentacion comandos

Approved-by: Jonathan Teran

README.md

@@ -1,3 +1,71 @@
 # Git Flow
 
-Herramienta para establecer un workflow y versionar un repositorio
+Herramienta para establecer un workflow siguiendo [Conventional Commits
+(CC)](https://www.conventionalcommits.org), [Conventional Branch
+(CB)](https://conventional-branch.github.io/), y [SemVer](https://semver.org/).
+
+Esta diseñada para facilitar la creación de commits y branches en un formato estandar, que permite
+derivar versiones automaticamente de los merges sobre ramas principales.
+
+## Configuración
+
+Para poder usar la herramienta en un repositorio, necesitamos inicializarlo:
+
+```sh
+git-flow init
+```
+
+El comando solicitará 2 opciones:
+
+- **Ramas principales**: Ramas que representan los entornos principales del proyecto. Por ejemplo:
+  `dev,test,prod`.
+- **Remoto** (opcional): Nombre del remoto que se usará para crear PRs, y taggear merges
+  automáticamente. Por el momento, se soportan los siguientes remotos:
+
+  - [x] Bitbucket
+  - [ ] Github: planeado
+
+  La configuración del remoto requiere tener un API Token para poder crear los PRs automáticamente.
+  El mismo se puede crear desde: *"Atlassian Account Settings" > "Security" > "Create and Manage API
+  Tokens" > "Create API Tokens with scopes"*. El token necesita el scope `write:pullrequest:bitbucket`
+
+  - `write:repository:bitbucket`
+
+  Luego se debe guardar el token dentro del repositorio a configurar, en el archivo `.repository-token`.
+
+  De no especificarse, los merges y tags se harán de forma local.
+
+## Utilización
+
+Git Flow cuenta con 5 comandos principales para guiar el workflow (ver `git-flow <command> -h` para
+más información):
+
+- `new`: Crea una nueva rama siguiendo CB.
+- `commit`: Crea un commit siguiendo CC.
+- `merge`: Mergea la rama actual a una de las ramas principales.
+- `tag`: Crea un tag sobre el ultimo merge siguiendo SemVer.
+- `release`: Prepara la rama actual para pasarse al siguiente entorno configurado
+
+El workflow para el cual se penso la herramienta es el siguiente:
+
+1. Sobre la primer rama principal configurada (por ejemplo, `dev`), se crea una nueva rama con
+   `git-flow new`
+2. Se realizan cambios y se commitean los mismos con `git-flow commit` (se repite hasta que se
+   considere que la rama esté lista para mergear)
+3. Se ejecuta `git-flow merge` para mergear la rama al entorno que corresponda (en este caso,
+   `dev`). En caso de tener un remoto configurado, el comando crea un PR para integrar el cambio. Si
+   no, simplemente se ejecuta un `git merge` simple.
+4. Para versionar este último merge, se ejecuta `git-flow tag`, ya sea localmente o desde un
+   pipeline para que se ejecute en cada merge.
+5. Una vez que la rama fue correctamente integrada a un entorno (por ejemplo, `dev`), se usa
+   `git-flow release` para crear una nueva rama para integrar unicamente los cambios de esa rama
+   sobre el siguiente entorno (por ejemplo, `test`). Si la rama original era
+   `feature/my-new-feature`, se crea la rama `release/test/feature/my-new-feature` sobre `test` que
+   tiene los cambios de la rama original.
+
+## Taggeo automático por pipeline
+
+Éste repositorio utiliza Git Flow para el taggeo automático usando pipelines, se puede ver el
+archivo `bitbucket-pipelines.yml` como ejemplo. El comando `git-flow tag` soporta el pasaje del
+token mediante la opción `--token=<TOKEN>`. Ver la sección [Configuración](#configuracion) para las
+instrucciones de como generar este token. El mismo necesita scope `write:repository:bitbucket`.

src/git_flow/__init__.py

@@ -6,6 +6,7 @@ BRANCH_TYPES = [
     "bugfix",
     "hotfix",
     "chore",
+    "docs",
 ]
 
 COMMIT_TYPES = [

src/git_flow/main.py

@@ -40,7 +40,7 @@ class GitFlowCommand(Command):
         subparsers = parser.add_subparsers(title="comandos", dest="command", required=True)
 
         for command in self.commands:
-            subparser = subparsers.add_parser(command.name())
+            subparser = subparsers.add_parser(command.name(), description=command.description())
             command.setup_parser(subparser)
 
         return parser