Como Crear y Utilizar un Flujo de Documentación de Fedora Local

Fedora Documentation Team Last review: 2024-08-30
En un entorno local, puedes crear o editar tus documentos sin conexión. Utilizas un repositorio Git local que contiene un conjunto completo de documentos y herramientas para editar. Una vez finalizada la edición, puedes previsualizarlos en una compilación local de páginas de Docs. Es, sin duda, la forma más flexible de trabajar con repositorios de Docs, gracias a su amplia adaptación a las rutinas y equipos de trabajo individuales. Un entorno de escritura local permite acceso completo a todos los recursos que utilizas habitualmente en su estación de trabajo y, por lo tanto, se adapta perfectamente a su estilo de trabajo. Es especialmente adecuado para la creación de documentación completamente nueva sobre un tema o para la revisión de documentación existente. Este artículo utiliza como ejemplo los repositorios del proyecto Fedora en GitLab, pero el proceso general se puede aplicar a proyectos de Pagure y GitHub.

Requisitos previos

  1. Necesita completar los requisitos básicos como especificó en Write contributions to Docs.

  2. El flujo de trabajo utiliza herramientas de la línea de comando en muchos pasos del proceso. Tener alguna experiencia trabajando en el Terminal Linux es por lo tanto necesario o debe ser aprendido en paralelo.

Configura un entorno de autoridad

Preparaciones

  1. Utilice llaves SSH para autenticar al servidor GitLab remoto.

  2. Una clave GPG (GNU Privacy Guard) está para firmar las verificaciones de ejecuciones.

En GitLab, vaya a preferencias → Opciones de Usuario → Añadir una Clave SSH / una Clave GPG

Git y Podman vienen con Fedora Workstation por defecto. El contenedor de Podman está configurado automáticamente.

Cree un subdirectorio local donde el clon del repo de Docs está almacenado

Cree el directorio principal con mkdir NombreDirectorio

$ mkdir ~/FedoraDocs

Configurar el repositorio

Bifurcar un proyecto

En GitLab, vaya al repositorio de arriba y seleccione el botón de bifurcación Fork en la cima. Seleccione un espacio de nombre (su ID de GitLab) y un nivel de visibilidad para el proyecto bifurcado, el cual crea una bifurcación para su cuenta GitLab.

Si no tiene acceso para crear un proyecto, abra un ticket de incidencia en GitLab para crear uno por usted.

Clonar el repositorio

En su repositorio bifurcado, selecciona el botón azul Clonar y luego Clonar con SSH. Copie el enlace a su portapapeles.

Vaya a su directorio de documentos principal, y clone el repo.

$ cd FedoraDocs

Cuando clone un repositorio, puede especificar el nombre del directorio nuevo como un argumento adicional. Esto crea un subdirectorio ContributorsGuide y clona el repo en ese directorio.

$ git clone <GIT URL> ContributorsGuide
$ cd ContributorsGuide

Marque la rama actual, la cual es principal o maestra.

$ git status

Muestre todas las ramas en el remoto.

$ git branch -v -a

Para crear una rama y cambiar a ella,

$ git checkout -b <rama-nueva>

Trabajar con el contenido

Abra el/los archivo/s con su elección de editor de texto, edite, y guarde.

Sincronice su bifurcación con el repositorio principal

$ git remote -v

Esto mostrará la bifurcación en su cuenta como el origen.

Vaya al repo principal, y seleccione el botón Clonar arrastrar-soltar, y copie el Clon con el informe de SSH.

$ git remote add upstream <SSH URL>

Ejecute el comando debajo para mostrar ambos origen y ascendente.

$ git remote -v

Para conservar su bifurcación en sincronía con ascendente,

$ git checkout main
$ git fetch upstream
$ git pull upstream main

Este comando obtiene los commits más recientes desde el flujo superior a su rama local.

$ git push origin main

Este comando empuja su commit local a la rama principal del origen remoto.

Ejecute los guiones para vista previa localmente

Vaya al directorio donde el repo está clonado, y ejecute los guiones de compilación en el terminal.

$ ./docsbuilder.sh

Previsualice su explorador utilizando la dirección de localhost:8080

Guarde su trabajo

Consulte que ha sido cambiado con los comandos ‘git add’ y ‘git commit’.

$ git status

Para añadir cambios los cuales serán efectuados,

$ git add -A

Alternativamente, para añadir todos los archivos en el directorio de trabajo actual,

$ git add .

Prepare los cambios para subir, lo cual abrirá el editor de texto para añadir mensaje efectuado.

$ git commit -s

El comando git log exhibe el historial del proyecto y los cambios específicos.

$ git log

Sube los cambios a su rama en su bifurcación.

$ git push origin <nombre-rama>

Cree solicitudes de unión

Vaya a su bifurcación del repositorio en GitLab.

En el menú izquierdo, pulse Merge Request, y seleccione el New merge request azul en el medio.

Cuando trabaje en una bifurcación, seleccione su bifurcación del repositorio como la rama origen.

En el listado desplegable de rama Destino, seleccione la rama desde el repositorio ascendente como rama de destino.

Pulse en las ramas compare y continúe.

Seleccione solicitud Crear unión.