Realizar cambios importantes en la documentación de Microsoft Learn

  • Artículo

Importante

Todos los repositorios que publican en Microsoft Learn han adoptado el Código de conducta de código abierto de Microsoft o el Código de conducta de .NET Foundation. Para más información, consulte las preguntas frecuentes sobre el código de conducta. O bien póngase en contacto con opencode@microsoft.com o conduct@dotnetfoundation.org para enviar sus preguntas o comentarios.

Las correcciones menores o aclaraciones realizadas a la documentación y los ejemplos de código de los repositorios públicos se rigen por las Condiciones de uso de learn.microsoft.com. Los cambios importantes o nuevos generarán un comentario en la solicitud de incorporación de cambios para solicitarle que acepte el contrato de licencia de colaboración (CLA, por sus siglas en inglés) si no es un empleado de Microsoft. Deberá rellenar el formulario en línea para que se pueda fusionar la solicitud de incorporación de cambios.

Este artículo describe cómo cambiar un artículo de Microsoft Learn con herramientas locales y resulta conveniente para un colaborador que necesita realizar un cambio importante o que será un colaborador frecuente de un repositorio. Los colaboradores frecuentes suelen realizar cambios constantes de larga duración que pasan por varios ciclos de compilación, validación y almacenamiento provisional o duran varios días antes de aprobar la solicitud de incorporación de cambios.

Los ejemplos de estos tipos de colaboradores incluyen:

  • Haga una gran contribución. Por ejemplo, sus contribuciones (adiciones, cambios o eliminaciones) podrían abarcar varios artículos y podría ser necesario confirmarlas y probarlas como una unidad de trabajo en una única solicitud de incorporación de cambios.
  • Cree y publique un artículo nuevo, lo cual normalmente requiere un editor local más sólido.
  • Agregue nuevas imágenes o actualice las existentes, cosa que normalmente requiere crear un subdirectorio media nuevo de forma simultánea, crear archivos de imagen, actualizar los vínculos a las imágenes en los artículos y obtener la versión preliminar de los archivos Markdown en un editor local para probar la representación de las imágenes.
  • Actualice un artículo durante un período de días antes de su publicación. En estos casos, por lo general, sería necesario integrar normalmente otros cambios que se produzcan en la rama predeterminada. Esta integración es más sencilla mediante Git Bash y la edición local. También existe el riesgo de perder las modificaciones si lo hace a través del editor web de GitHub y espera antes de confirmar los cambios.
  • Realice actualizaciones continuas en el mismo artículo después de abrir una solicitud de incorporación de cambios. Aunque puede usar el editor web de GitHub para este fin, puede crear varias solicitudes de incorporación de cambios pendientes para el mismo archivo, que podrían entrar en conflicto entre ellas.

Requisitos previos

Crear y modificar la rama de trabajo

Para empezar, cree una nueva rama de trabajo en su repositorio local para capturar los cambios propuestos. Para obtener más información sobre las ramas, consulte Aspectos básicos de Git y GitHub.

En este tutorial se usa Git Bash y Visual Studio Code, pero puede usar el cliente y el editor de Git que prefiera.

  1. En VS Code, abra la carpeta del repositorio de la clonación local. En el menú Archivo, seleccione Abrir carpeta y vaya a la carpeta del equipo.

  2. Seleccione Ver en el menú superior y, a continuación, seleccione Terminal para abrir el terminal integrado.

  3. En el terminal integrado, asegúrese de que está en la carpeta del repositorio.

  4. Antes de crear una rama de trabajo, asegúrese de que la rama principal local esté actualizada con todo lo que hay en la rama principal del repositorio de producción. Esta tarea garantiza que la rama de trabajo capture los cambios que se han producido en el repositorio de producción desde la última vez que se completó una sincronización.

    1. Cambie a la rama principal del repositorio local:

      git checkout main

    2. Asegúrese de que la rama principal local esté actualizada:

      git pull upstream main

  5. Cree una rama de trabajo local basada en la principal:

    git checkout -b <branch-name>

    <branch-name> es un marcador de posición. Al ejecutar el comando, reemplácelo por un nombre único y significativo para la rama y quite los corchetes angulares.

  6. Inserte la rama de trabajo local en la rama remota en la bifurcación de GitHub:

    git push origin <branch-name> -u

    La opción -u vincula las ramas local y remota. Esta opción permite insertar confirmaciones en la bifurcación con solo escribir git push en lugar de git push origin <branch-name>.

Búsqueda del archivo Markdown de origen

Para editar un artículo, busque el archivo de origen del artículo en el clon del repositorio local. En VS Code, acceda a los archivos Markdown del repositorio a través del explorador de archivos (un icono de documento en la barra lateral superior izquierda). El explorador de archivos muestra la estructura de carpetas del repositorio y le permite ir al archivo que desea editar.

Si no encuentra el archivo, visite el artículo de Microsoft Learn y seleccione el icono de lápiz Editar. La ubicación de la carpeta relacionada en el repositorio de GitHub se muestra en la dirección URL. Esta es una dirección URL del vínculo Editar de ejemplo:

   https://github.com/Microsoft/azure-docs/blob/main/articles/azure-functions/functions-overview.md

Esta es una ubicación de archivo de ejemplo para esta dirección URL.

   C:\GitHub\*\azure-docs\articles\azure-functions\functions-overview.md

Edición del archivo

  1. Para abrir el archivo en VS Code, selecciónelo.
  2. Haga los cambios que desee.
  3. Guarde los cambios. Para ello, seleccione Archivo>Guardar. Use Guardar todo para guardar varios archivos a la vez.

Confirmación y envío de cambios

Si ha realizado modificaciones sustanciales o ha revisado un artículo para actualizarlo, cambie ms.date en el bloque de metadatos en la parte superior del archivo. Ajuste el formato de fecha a mm/dd/aaaa.

Puede usar el terminal de VS Code o la interfaz de usuario de VS Code para confirmar e insertar los cambios.

  1. Ejecute el comando git status para comprobar que solo aparecen los archivos que editó en la lista de archivos modificados.

    git status

  2. Ejecute el comando git add seguido de la ruta de acceso del archivo y el nombre de archivo para almacenar provisionalmente el archivo que ha cambiado.

    git add folder-name/file-name.md

    Si ha cambiado varios archivos, escriba un comando git add para cada archivo.

    Como alternativa, puede ejecutar git add . (tenga en cuenta el período después de add) para almacenar provisionalmente y automáticamente todos los cambios realizados. Este método es más rápido, pero puede provocar problemas mediante la inclusión de cambios realizados por accidente.

  3. Vuelva a ejecutar git status para confirmar los cambios que se han almacenado provisionalmente.

  4. Ejecute el comando git commit seguido de un mensaje de confirmación para guardar los cambios en el repositorio clonado local.

    git commit -m "your commit message"

  5. Ejecute git push para insertar los cambios.

    git push

Lo ha conseguido. El código se encuentra ya en el repositorio de GitHub y usted está a punto para abrir una solicitud de incorporación de cambios.

¿Necesita corregir algo que ha enviado? Es muy sencillo. Repita los pasos anteriores, empezando por editar el archivo, para realizar los cambios en la misma rama y, luego, confirmarlos y volver a enviarlos; no es necesario establecer el servidor que precede en la cadena en inserciones posteriores de la misma rama. Por lo general, las ramas se usan para separar flujos de trabajo, por lo que no es necesario crear una nueva rama a menos que esté listo para trabajar en otra tarea.

Realización de los próximos cambios

¿Listo para realizar otro cambio no relacionado con este? Vuelva a la rama predeterminada, incorpore cambios del repositorio ascendente para actualizar la bifurcación y extraiga del repositorio una nueva rama. Ejecute los comandos siguientes en Git Bash:

git checkout main
git pull upstream main
git checkout -b "branchname"
git push origin <branch-name> -u

Ahora está en una nueva rama vinculada a la rama remota y está listo para realizar más cambios. Ya le queda poco para convertirse en colaborador experto.

Pasos siguientes