Flujo de trabajo de colaboración de GitHub para cambios mayores o de larga duraciónGitHub contribution workflow for major or long-running changes

Importante

Todos los repositorios que publican en docs.microsoft.com han adoptado el Código de conducta de código abierto de Microsoft o el Código de conducta de .NET Foundation.All repositories that publish to docs.microsoft.com have adopted either the Microsoft Open Source Code of Conduct or the .NET Foundation Code of Conduct. Para obtener más información, vea las preguntas más frecuentes del Código de conducta.For more information, see the Code of Conduct FAQ. O bien póngase en contacto con opencode@microsoft.com o conduct@dotnetfoundation.org para enviar sus preguntas o comentarios.Or contact opencode@microsoft.com, or conduct@dotnetfoundation.org with any questions or comments.

Las correcciones menores o aclaraciones de la documentación y los ejemplos de código de los repositorios públicos se rigen por los Términos de uso del sitio docs.microsoft.com.Minor corrections or clarifications to documentation and code examples in public repositories are covered by the docs.microsoft.com Terms of Use. 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.New or significant changes will generate a comment in the pull request, asking you to submit an online Contribution License Agreement (CLA) if you are not an employee of Microsoft. Deberá rellenar el formulario en línea para que se pueda fusionar la solicitud de incorporación de cambios.You will need to complete the online form before your pull request can be merged.

Información generalOverview

Este flujo de trabajo resulta conveniente para un colaborador que necesita realizar un cambio mayor o que será un colaborador frecuente de un repositorio.This workflow is suitable for a contributor who needs to make a major change or will be a frequent contributor to a repository. 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 y fusionar la solicitud de incorporación de cambios.Frequent contributors typically have ongoing (long-running) changes, which go through multiple build/validation/staging cycles or span multiple days before pull request sign-off and merge.

Los ejemplos de estos tipos de colaboradores incluyen:Examples of these types of contributions include:

  • Haga una gran contribución.Making a large contribution. Por ejemplo, podría hacer contribuciones (adiciones, cambios o eliminaciones) que abarquen varios artículos y que sea necesario confirmar y probar como una unidad de trabajo en una única solicitud de incorporación de cambios.For instance, you might make contributions (additions, changes, or deletions) that span multiple articles and need to be committed and tested as one unit of work in a single pull request.
  • Cree y publique un artículo nuevo, lo cual normalmente requiere un editor local más sólido.Creating and publishing a new article, which typically requires a more robust local editor.
  • Agregue nuevas imágenes o actualice las existentes, cosa que normalmente requiere los archivos de las imágenes, así como crear un subdirectorio media nuevo de forma simultánea, 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.Adding new images or updating images, which typically requires simultaneous creation of a new media subdirectory, image files, updates to image links in articles, and previewing markdown files in a local editor to test image rendering.
  • Actualice un artículo durante un período de días antes de su publicación.Updating an article over a period of days before you publish. En estos casos, por lo general, sería necesario integrar normalmente otros cambios que se produzcan en la rama "master".In these cases, you typically need to do regular integration of other changes that occur in the master branch. Esta integración es más sencilla mediante Git Bash y la edición local.This integration is easier via Git Bash and local editing. También existe el riesgo de perder las modificaciones si lo hace a través de la IU de GitHub y espera antes de confirmar los cambios.You also run the risk of losing your edits if you do this via the GitHub UI and wait before you commit the changes.
  • Actualice el mismo artículo de forma continuada después de que se haya abierto una solicitud de incorporación de cambios, a no ser que sea más cómodo hacerlo a través la IU de GitHub.Making continual updates to the same article after a pull request has been opened (unless you are comfortable doing this via the GitHub UI). El uso de la IU de GitHub ofrece la posibilidad de crear varias solicitudes de incorporación de cambios pendientes para el mismo archivo, lo cual puede crear conflictos con otras.Using the GitHub UI has the potential to create multiple outstanding pull requests for the same file, which may conflict with one another.

TerminologíaTerminology

Antes de empezar, debe revisar algunos de los términos y moniker de Git/GitHub utilizados en este flujo de trabajo.Before you start, let's review some of the Git/GitHub terms and monikers used in this workflow. No se preocupe ahora si no los entiende.Don't worry about understanding them now. Solo debe saber que la información proporcionada está relacionada con ellos y que puede volver a consultar esta sección cuando necesite comprobar una definición.Just know that you will be learning about them, and you can refer back to this section when you need to verify a definition.

NameName DescripciónDescription
bifurcaciónfork Suele usarse como sustantivo para hacer referencia a una copia de un repositorio principal de GitHub.Normally used as a noun, when referring to a copy of a main GitHub repository. En la práctica, una bifurcación no es más que otro repositorio.In practice, a fork is just another repository. No obstante, resulta especial por el hecho de que GitHub establece una nueva conexión con el repositorio principal o primario.But it's special in the sense that GitHub maintains a connection back to the main/parent repository. A veces se usa como verbo, como en el caso de "Primero debe bifurcar el repositorio".It's sometimes used as a verb, as in "You must fork the repository first."
Conexión remotaremote Una conexión con nombre a un repositorio remoto, como la conexión remota con el "origen" o con el repositorio "ascendente".A named connection to a remote repository, such as the "origin" or "upstream" remote. Git hace referencia a esto con el término "conexión remota", ya que se usa para hacer referencia a un repositorio hospedado en otro equipo.Git refers to this as remote because it is used to reference a repository that's hosted on another computer. En este flujo de trabajo, una conexión remota es siempre un repositorio de GitHub.In this workflow, a remote is always a GitHub repository.
origenorigin El nombre asignado a la conexión entre el repositorio local y el repositorio a partir del que se ha realizado la clonación.The name assigned to the connection between your local repository and the repository from which it was cloned. En este flujo de trabajo, el origen representa la conexión con la bifurcación.In this workflow, origin represents the connection to your fork. A veces se usa como un moniker para el repositorio de origen, como en "Recuerde insertar los cambios en el origen".It's sometimes used as a moniker for the origin repository itself, as in "Remember to push your changes to origin."
ascendenteupstream Como la conexión remota al origen, el término "ascendente" se corresponde con una conexión con nombre a otro repositorio.Like the origin remote, upstream is a named connection to another repository. En este flujo de trabajo, el término "ascendente" representa la conexión entre el repositorio local y el repositorio principal a partir del que se creó la bifurcación.In this workflow, upstream represents the connection between your local repository and the main repository, from which your fork was created. A veces se usa como un moniker para el repositorio ascendente, como en "Recuerde extraer los cambios del repositorio ascendente".It's sometimes used as a moniker for the upstream repository itself, as in "Remember to pull the changes from upstream."

Flujo de trabajoWorkflow

Importante

Si aún no lo ha hecho, debe completar estos pasos en la sección de configuración.If you haven't already, you must complete the steps in the Setup section. Esta sección sirve de guía para configurar la cuenta de GitHub, instalar Git Bash y Markdown editor, crear una bifurcación y configurar el repositorio local.This section walks you through setting up your GitHub account, installing Git Bash and a Markdown editor, creating a fork, and setting up your local repository. Si no está familiarizado con los conceptos de Git o de GitHub, como los repositorios o las ramas, primero revise el artículo Aspectos básicos sobre Git y GitHub.If you are unfamiliar with Git and GitHub concepts such as a repository or branch, please first review Git and GitHub fundamentals.

En este flujo de trabajo, los cambios se realizan dentro de un ciclo repetitivo.In this workflow, changes flow in a repetitive cycle. A partir del repositorio local del dispositivo, los cambios se dirigen a la bifurcación de GitHub, entran en el repositorio principal de GitHub y vuelven a la ubicación local mientras se incorporan los cambios de otros colaboradores.Starting from your device's local repository, they flow back up to your GitHub fork, into the main GitHub repository, and back down locally again as you incorporate changes from other contributors.

Uso del flujo de GitHubUse GitHub flow

Según se indica en el artículo Aspectos básicos sobre Git y GitHub, un repositorio de Git contiene una bifurcación principal, además de ramas de trabajo en proceso que no se han integrado en la principal.Recall from Git and GitHub fundamentals that a Git repository contains a master branch, plus any additional work-in-progress branches that have not been integrated into master. Siempre que incorpore un conjunto de cambios relacionados de forma lógica, un procedimiento recomendado consiste en crear una rama de trabajo para administrar los cambios a través del flujo de trabajo.Whenever you introduce a set of logically related changes, it’s a best practice to create a working branch to manage your changes through the workflow. Se hace referencia aquí a ello como rama de trabajo porque se trata de un área de trabajo donde se iteran y se refinan los cambios, hasta que se vuelven a integrar en la rama principal.We refer to it here as a working branch because it's a workspace to iterate/refine changes, until they can be integrated back into the master branch.

El aislamiento de cambios relacionados en una rama específica permite controlar e incorporar dichos cambios de forma independiente, para centrarse en ellos en un momento de lanzamiento especifico durante el ciclo de publicación.Isolating related changes to a specific branch allows you to control and introduce those changes independently, targeting them to a specific release time in the publishing cycle. En realidad, en función del tipo de trabajo que realice, podría terminar fácilmente con varias ramas de trabajo en el repositorio.In reality, depending on the type of work you do, you can easily end up with several working branches in your repository. No es raro trabajar en varias ramas al mismo tiempo, pues cada una de ellas representa un proyecto diferente.It's not uncommon to be working on multiple branches at the same time, each representing a different project.

Sugerencia

Realizar los cambios directamente en la rama principal no es un procedimiento recomendado.Making your changes in the master branch is not a good practice. Imagine que usa la rama principal para incorporar una serie de cambios para el lanzamiento de una característica en un momento determinado.Imagine that you use the master branch to introduce a set of changes for a timed feature release. Ha terminado de incorporar los cambios y espera a que se lancen.You finish the changes and are waiting to release them. Mientras tanto, tiene una solicitud urgente para corregir algo, por lo que hace un cambio en un archivo en la rama principal y después publica el cambio.Then in the interim, you have an urgent request to fix something, so you make the change to a file in the master branch and then publish the change. En este ejemplo, publicaría de forma involuntaria la corrección y los cambios cuyo lanzamiento esperaba en una fecha concreta.In this example, you inadvertently publish both the fix and the changes that you were holding for release on a specific date.

Ahora vamos a crear una rama de trabajo en el repositorio local, para capturar los cambios propuestos.Now let's create a new working branch in your local repository, to capture your proposed changes. Cada cliente de Git es diferente, así que consulte la ayuda para su cliente preferido.Each git client is different, so consult the help for your preferred client. Puede ver un resumen del proceso en la guía de GitHub, en GitHub Flow.You can see an overview of the process in the GitHub Guide on GitHub flow.

Procesamiento de solicitudes de incorporación de cambiosPull request processing

La sección anterior le guía en el proceso de envío de enviar los cambios propuestos, agrupados en una nueva solicitud de incorporación de cambios (PR) que se agrega a la cola de solicitudes de incorporación de cambios del repositorio de destino.The previous section walked you through the process of submitting proposed changes, by bundling them in a new pull request (PR) that is added to the destination repository's PR queue. Una solicitud de incorporación de cambios permite el modelo de colaboración de GitHub. Para ello, se solicita que se "incorporen" los cambios de la rama de trabajo y se combinen con los de otra rama.A pull request enables GitHub's collaboration model, by asking for the changes from your working branch to be pulled and merged into another branch. En la mayoría de los casos, la otra rama es la rama predeterminada/"master" en el repositorio principal.In most cases, that other branch is the default/master branch in the main repository.

ValidaciónValidation

Antes de que la solicitud de incorporación de cambios se pueda combinar en su rama de destino, puede que sea necesario pasar uno o varios procesos de validación de PR.Before your pull request can be merged into its destination branch, it might be required to pass through one or more PR validation processes. Los procesos de validación pueden variar en función del alcance de los cambios propuestos y de la reglas del repositorio de destino.Validation processes can vary depending on the scope of proposed changes and the rules of the destination repository. Tras enviar la solicitud de incorporación de cambios, cabría esperar que suceda algo de lo siguiente:After your pull request is submitted, you can expect one or more of the following to happen:

  • Capacidad de combinación: primero se realiza una prueba de la capacidad de combinación de GitHub de línea base para comprobar que los cambios propuestos en la rama no entren en conflicto con la rama de destino.Mergeability: A baseline GitHub mergeability test occurs first, to verify whether the proposed changes in your branch are not in conflict with the destination branch. Si la solicitud de incorporación de cambios indica que no se ha superado la prueba, será necesario reconciliar el contenido que provoca los conflictos que impiden la combinación para continuar con el proceso.If the pull request indicates that this test failed, you must reconcile the content that is causing the merge conflict before processing can continue.
  • CLA: si contribuye a un repositorio público y no es empleado de Microsoft, según la magnitud de los cambios propuestos, es posible que se le solicite que rellene un breve Contrato de licencia de colaboración (CLA) la primera vez que envíe una solicitud de incorporación de cambios a ese repositorio.CLA: If you are contributing to a public repository and are not a Microsoft employee, depending on the magnitude of the proposed changes, you might be asked to complete a short Contribution License Agreement (CLA) the first time you submit a pull request to that repository. Después de que se realiza el paso del CLA, se procesa la solicitud de incorporación de cambios.After the CLA step is cleared, your pull request is processed.
  • Etiquetado: se aplican automáticamente etiquetas a la solicitud de incorporación de cambios para indicar su estado a medida que pasa por el flujo de trabajo de validación.Labeling: Labels are automatically applied to your pull request, to indicate the state of your pull request as it passes through the validation workflow. Por ejemplo, una nueva solicitud de incorporación de cambios podría recibir automáticamente la etiqueta "no combinar", que indica que la solicitud de incorporación de cambios aún no ha completado los pasos de validación, revisión y aprobación.For instance, new pull requests might automatically receive the "do-not-merge" label, indicating that the pull request has not yet completed the validation, review, and sign-off steps.
  • Validación y compilación: comprobaciones automatizadas certifican que los cambios pasan las pruebas de validación.Validation and build: Automated checks verify whether your changes pass validation tests. Las pruebas de validación pueden generar avisos o errores que requieran realizar cambios en uno o varios archivos de la solicitud de incorporación de cambios antes de poder combinarla.The validation tests might yield warnings or errors, requiring you to make changes to one or more files in your pull request before it can be merged. Los resultados de la prueba de validación se agregan como comentario a la solicitud de incorporación de cambios para que puedan revisarse posteriormente y enviarse por correo electrónico.The validation test results are added as a comment in your pull request for your review, and they might be sent to you in e-mail.
  • Ensayo: las páginas del artículo afectadas por los cambios se implementan automáticamente en un entorno de ensayo para revisarlas una vez que se han validado y compilado correctamente.Staging: The article pages affected by your changes are automatically deployed to a staging environment for review upon successful validation and build. En los comentarios de solicitud de incorporación de cambios, aparecen direcciones URL de vista previa.Preview URLs appear in a PR comment.
  • Combinación automática: si la solicitud de incorporación de cambios supera la prueba de validación y cumple ciertos criterios, puede combinarse automáticamente.Auto-merge: The pull request might be automatically merged, if it passes validation testing and certain criteria. En este caso, no es necesario realizar ninguna acción.In this case, you don't need to take any further action.

Revisión y aprobaciónReview and sign-off

Una vez que han finalizado todos los procesos de la solicitud de incorporación de cambios, convendría revisar los resultados (comentarios de la solicitud de incorporación de cambios, las URL de vista previa, etc.) para determinar si es necesario realizar más cambios en los archivos antes de que se aprueben para la combinación.After all PR processing is completed, you should review the results (PR comments, preview URLs, etc.) to determine if additional changes to its files are required before you sign off for merging. Si el revisor de una solicitud de incorporación de cambios ya ha revisado la solicitud y ha detectado algunos problemas o cuestiones destacados que deban resolverse antes de la combinación, también puede proporcionar sus comentarios.If a PR reviewer has reviewed your pull request, they can also provide feedback via comments if there are outstanding issues/questions to be resolved prior to merge.

La automatización de comentarios permite que los usuarios con nivel de lectura (es decir, aquellos que no tienen permisos de escritura en un repositorio) realicen una acción de nivel de escritura, mediante la asignación de la etiqueta adecuada a una solicitud de incorporación de cambios.Comment automation enables read-level users (users who don't have write permissions in a repo) to perform a write-level action, by assigning the appropriate label to a pull request. Si trabaja en un repositorio en el que se ha implementado la automatización de comentarios, use los comentarios de hashtag que se muestran en la tabla siguiente para asignar etiquetas, cambiar etiquetas o cerrar una solicitud de incorporación de cambios.If you are working in a repository where comment automation has been implemented, use the hashtag comments listed in the following table to assign labels, change labels, or close a pull request. Los empleados de Microsoft también recibirán una notificación por correo electrónico para que revisen y aprueben las solicitudes de incorporación de cambios de los repositorios públicos cada vez que se propongan cambios en los artículos que usted haya creado.Microsoft employees will also be notified via e-mail for review and sign-off of public repository PRs, whenever changes are proposed to articles for which you are the author.

Comentario de hashtagHashtag comment Qué haceWhat it does Disponibilidad de repositorioRepo availability
#sign-off Cuando el autor de un artículo escribe el comentario #sign-off en la secuencia de comentarios, se asigna la etiqueta ready-to-merge.When the author of an article types the #sign-off comment in the comment stream, the ready-to-merge label is assigned. Esta etiqueta permite que los revisores del repositorio sepan en qué momento una solicitud de incorporación de cambios está lista para que se revise o se fusione.This label lets the reviewers in the repo know when a pull request is ready for review/merge.

Si un colaborador que no es el autor especificado intenta aprobar una solicitud de incorporación de cambios pública mediante el comentario #sign-off, se escribe un mensaje en dicha solicitud para indicar que solo el autor puede asignar la etiqueta.If a contributor who is not the listed author tries to sign off on a public repo pull request by using the #sign-off comment, a message is written to the pull request indicating that only the author can assign the label.
Público y privadoPublic and private
#hold-off Los autores pueden escribir #hold-off en el comentario de una solicitud de incorporación de cambios para eliminar la etiqueta ready-to-merge en caso de que cambien de opinión o de que hayan cometido un error.Authors can type #hold-off in a PR comment to remove the ready-to-merge label--in case they change their mind or make a mistake. En el repositorio privado, esto asigna la etiqueta do-not-merge.In the private repo, this assigns the do-not-merge label. Público y privadoPublic and private
#please-close Los autores pueden escribir #please-close en la secuencia de comentarios para cerrar la solicitud de incorporación de cambios si deciden no fusionar los cambios.Authors can type #please-close in the comment stream to close the pull request if they decide not to have the changes merged. PúblicoPublic

Una vez que la solicitud no presente ningún problema y esté aprobada, los cambios se combinan en la rama primaria y la solicitud de incorporación de cambios se cierra.When the pull request is issue-free and signed off, your changes are merged back into the parent branch and the pull request is closed.

PublicaciónPublishing

Recuerde que la solicitud de incorporación de cambios debe combinarla un revisor antes de que los cambios se incluyan en la siguiente ronda programada de publicación.Remember, your pull request has to be merged by a PR reviewer before the changes can be included in the next scheduled publishing run. Normalmente, las solicitudes se revisan o combinan según el orden de envío.Pull requests are normally reviewed/merged in the order of submission. Si la solicitud de incorporación de cambios debe combinarse para una ronda de publicación específica, deberá trabajar con el revisor de la solicitud con la antelación suficiente para garantizar que la combinación se realice a tiempo.If your pull request requires merging for a specific publishing run, you will need to work with your PR reviewer ahead of time to ensure that merging happens prior to publishing.

Una vez que se hayan aprobado y combinado las contribuciones, el proceso de publicación Docs.Microsoft.Com las recoge.After your contributions are approved and merged, the docs.microsoft.com publishing process picks them up. Dependiendo del equipo que administre el repositorio en el que esté realizando la contribución, el tiempo de publicación puede variar.Depending on the team that manages the repository you are contributing to, publishing times can vary. Los artículos publicados en las siguientes rutas de acceso normalmente se implementan de lunes a viernes entre las 10:30 y las 15:30 (PST):Articles published under the following paths are normally deployed at approximately 10:30 AM and 3:30 PM Pacific Time, Monday-Friday:

Es posible que los artículos tarden hasta 45 minutos en aparecer en línea tras publicarlos.It can take up to 45 minutes for articles to appear online after publishing. Después de que el artículo se ha publicado, puede comprobar los cambios en la URL apropiada: https://docs.microsoft.com/<path-to-your-article-without-the-md-extension>.After your article is published, you can verify your changes at the appropriate URL: https://docs.microsoft.com/<path-to-your-article-without-the-md-extension>.

Pasos siguientesNext steps

Eso es todo.That's it! Ya ha hecho una colaboración en el contenido de docs.microsoft.com.You've made a contribution to docs.microsoft.com content!

  • Para obtener más información sobre temas como Markdown y la sintaxis de las extensiones de Markdown, continúe al artículo Aspectos básicos de escritura.To learn more about topics such as Markdown and Markdown extensions syntax, continue to the Writing essentials article.