Contribución a los repositorios de documentación de .NET

Le agradecemos el interés en colaborar con la documentación de .NET.

En este documento se describe el proceso para contribuir a los artículos y ejemplos de código que se hospedan en el sitio de documentación de .NET. Las contribuciones pueden ser tan simples como corregir errores ortográficos o tan complejos como redactar nuevos artículos.

El sitio de documentación de .NET se crea a partir de varios repositorios. Estos son algunos de ellos:

• Artículos conceptuales de .NET y fragmentos de código
• Ejemplos y fragmentos de código
• Referencia de API de .NET
• Referencia del SDK de .NET Compiler Platform
• Referencia de API de ML.NET

Instrucciones para las contribuciones

Agradecemos las contribuciones de la comunidad a la documentación. En la lista siguiente se muestran algunas reglas que se deben tener en cuenta a la hora de contribuir a la documentación de .NET:

• NO nos sorprenda con solicitudes de incorporación de cambios de gran tamaño. En su lugar, registre un asunto e inicie una discusión para que podamos definir un rumbo antes de dedicar una gran cantidad de tiempo.
• NO incluya código de ejemplo insertado en un artículo.
• Use un proyecto de fragmento de código con código para insertarlo en el artículo.
• SIGA estas instrucciones y directrices de voz y tono.
• USE el archivo de plantilla como punto de partida del trabajo.
• CREE una rama independiente en la bifurcación antes de trabajar en los artículos.
• SIGA el flujo de trabajo de GitHub.
• PUBLIQUE entradas de blog o tweets (o lo que prefiera) de sus contribuciones si quiere.

Seguir estas instrucciones garantizará una mejor experiencia para usted y para nosotros.

Proceso de contribución

Paso 1: Si está interesado en escribir nuevo contenido o en revisar exhaustivamente el contenido existente, abra una incidencia que describa lo que quiere hacer. El contenido de la carpeta docs se organiza en secciones que se reflejan en la tabla de contenido (TOC). Defina dónde se ubicará el tema en la tabla de contenido. Recabe opiniones sobre su propuesta.

O bien

Elija un problema existente y abórdelo. Puede examinar la lista de incidencias abiertas y trabajar de forma voluntaria en las que le interesen:

• Filtre por la etiqueta primera incidencia buena para ver las mejores incidencias para novatos.
• Filtre por la etiqueta se busca ayuda para ver incidencias adecuadas para colaboradores de la comunidad. Normalmente, estas incidencias no requieren casi contexto.
• Los colaboradores experimentados pueden abordar cualquier incidencia que les interese.

Cuando encuentre una incidencia en la que trabajar, agregue un comentario para preguntar si está abierta.

Una vez que haya elegido una tarea en la que trabajar, cree una cuenta de GitHub y vaya al paso 2.

Paso 2: Bifurque el repositorio /dotnet/docs (o el repositorio al que esté contribuyendo) según sea necesario y cree una rama para los cambios.

Para pequeños cambios, consulte Edición en el explorador.

Paso 3: Realice los cambios en esta nueva rama.

Si es un tema nuevo, puede usar esta plantilla como punto de partida. Contiene las instrucciones de escritura y la explicación de los metadatos necesarios para cada artículo, como la información del autor. Para más información sobre la sintaxis de Markdown usada en el contenido de Microsoft Learn, consulte Referencia de Markdown.

Vaya a la carpeta correspondiente a la ubicación de la tabla de contenido que se determinó para su artículo en el paso 1. Esa carpeta contiene los archivos Markdown de todos los artículos incluidos en esa sección. Si es necesario, cree una carpeta para colocar los archivos de su contenido. El artículo principal de esa sección se denomina index.md.

Para las imágenes y otros recursos estáticos, cree una subcarpeta denominada media dentro de la carpeta que contiene el artículo, si aún no existe. Dentro de la media carpeta, cree una subcarpeta con el nombre de artículo (excepto para el archivo de índice). Para obtener más información sobre dónde hay que colocar los archivos, vea la sección Ejemplo de estructura de carpetas.

No incluya código insertado en el artículo, a menos que muestre una construcción que no se compila. En su lugar, use un proyecto de fragmentos de código e incluya el código mediante la extensión de código. Esto garantiza que nuestro sistema de CI valida el código de ejemplo.

Para los fragmentos de código, cree una subcarpeta denominada snippets en la carpeta que contiene el artículo si todavía no se ha creado. Dentro de la carpeta de fragmentos, cree una subcarpeta con el nombre del artículo. En la mayoría de los casos, tendrá fragmentos de código para los tres lenguajes de .NET principales: C# , F# y Visual Basic. En ese caso, cree subcarpetas denominadas csharp, fsharp y vb para cada uno de los tres proyectos. Si va a crear un fragmento de código para un artículo en las carpetas docs/cssharp, docs/fsharp o docs/visual-basic, el fragmento de código solo estará en un idioma, por lo que puede omitir la subcarpeta de idioma. Para obtener más información sobre dónde hay que colocar los archivos, vea la sección Ejemplo de estructura de carpetas.

Los fragmentos de código son ejemplos pequeños y centrados en una cuestión concreta que muestran los conceptos que se describen en un artículo. Los programas más grandes, diseñados para su descarga y exploración, se encuentran en el repositorio dotnet/samples. Los ejemplos completos se describen en la sección sobre la contribución a los ejemplos.

Paso 4: Envíe una solicitud de incorporación de cambios (PR) desde su rama a la rama predeterminada.

En general, en cada PR se debe solucionar una incidencia a la vez, a menos que haya varios problemas relacionados con la misma corrección de PR. La PR puede modificar uno o varios archivos. Si se abordan varias correcciones en distintos archivos, es preferible usar PR independientes.

Si la PR corrige una incidencia existente, agregue la palabra clave Fixes #Issue_Number a la descripción de la PR. De este modo, la incidencia se podrá cerrar automáticamente cuando se combine la PR. Para obtener más información, vea Enlazar una solicitud de extracción a un informe de problemas utilizando una palabra clave.

El equipo de .NET revisará la PR y comunicará si es necesario realizar otras actualizaciones o modificaciones para aprobarla.

Paso 5: Realice las actualizaciones necesarias a la rama que haya acordado con el equipo.

Los mantenedores combinarán la PR en la rama predeterminada una vez que se hayan aplicado los comentarios y que se haya aprobado el cambio.

Periódicamente, se insertan todas las confirmaciones de la rama predeterminada a la rama activa, y después podrá ver su contribución activa en la documentación de .NET. Por lo general, se realizan publicaciones diarias durante la semana laboral.

Ejemplo de estructura de carpetas

docs
  /about
  /core
    /porting
      porting-overview.md
      /media
        /porting-overview
          portability_report.png
        /shared ...
      /snippets
        /porting-overview
          /csharp
            porting.csproj
            porting-overview.cs
            Program.cs
          /fsharp
            porting.fsproj
            porting-overview.fs
            Program.fs
          /vb
            porting.vbproj
            porting-overview.vb
            Program.vb
        /shared
          /csharp ...
          /fsharp ...
          /vb ...

La estructura que se muestra anteriormente incluye una imagen (portability_report.png) y tres proyectos de código que incluyen fragmentos de código que se detallan en el artículo porting-overview.md.

La carpeta snippets/shared se usa para los fragmento de código que pueden abarcar varios artículos dentro de la misma carpeta principal, como la carpeta porting del ejemplo anterior. Solo debe usar la carpeta shared cuando tenga un motivo concreto para hacerlo, como código XAML al que se hace referencia en varios artículos, pero no se pueda compilar en la carpeta article-specific.

Los elementos multimedia también se pueden compartir en varios artículos cuando estos artículos se encuentren en la misma carpeta principal, como porting en el ejemplo anterior. La carpeta shared debería evitarse, si es posible, y usarla únicamente cuando corresponda. Por ejemplo, podría tener sentido compartir una página común de carga para la aplicación que se mostrará, o bien compartir cuadros de diálogo de Visual Studio que se reutilicen en varios artículos.

Contribución a ejemplos

Realizamos la distinción siguiente para el código que admite nuestro contenido:

• Ejemplos: los lectores pueden descargar y ejecutar los ejemplos. Todos los ejemplos deben ser aplicaciones o bibliotecas completas. Si el ejemplo crea una biblioteca, debe incluir pruebas unitarias o una aplicación que permita a los lectores ejecutar el código. Por lo general, usan más de una tecnología, característica o kit de herramientas. En el archivo readme.md de cada ejemplo se hará referencia al artículo, para que se pueda leer más información sobre los conceptos descritos en cada ejemplo.
• Fragmentos de código: ilustran un concepto o una tarea de menor tamaño. Se compilan, pero no pretenden ser aplicaciones completas. Se deben ejecutar correctamente, pero no son una aplicación de ejemplo para un escenario típico. En su lugar, están diseñados con el menor tamaño posible para ilustrar un único concepto o característica. No deben ocupar más de una pantalla de código.

Los ejemplos se almacenan en el repositorio dotnet/samples. Trabajamos hacia un modelo en el que la estructura de nuestra carpeta samples coincide con la estructura de nuestra carpeta docs. Los estándares que seguimos son:

• Las carpetas de nivel superior coinciden con las carpetas de nivel superior del repositorio docs. Por ejemplo, el repositorio de documentos incluye una carpeta machine-learning/tutorials y los ejemplos para tutoriales de aprendizaje automático se encuentran en la carpeta samples/machine-learning/tutorials.

Además, todos los ejemplos de las carpetas core y standard se deben compilar y ejecutar en todas las plataformas compatibles con .NET Core. Nuestro sistema de compilación de CI aplicará esto. La carpeta framework de nivel superior contiene ejemplos que solo se compilan y validan en Windows.

Los proyectos de ejemplo se deben compilar en el conjunto de plataformas más amplio posible para el ejemplo proporcionado. En la práctica, eso significa la compilación de aplicaciones de consola basadas en .NET Core siempre que sea posible. Los ejemplos específicos de la web o marco de trabajo de la interfaz de usuario deben agregar esas herramientas según sea necesario. Algunos ejemplos son aplicaciones web, aplicaciones móviles, aplicaciones de WPF o WinForms, etc.

Estamos trabajando para implantar un sistema de integración continua para todo el código. Cuando actualice los ejemplos, asegúrese de que todas las actualizaciones formen parte de un proyecto que admita la compilación. Lo ideal sería agregar pruebas de exactitud también en los ejemplos.

Cada ejemplo completo que cree debe contener un archivo readme.md. Este archivo debe contener una descripción breve del ejemplo (uno o dos párrafos). Su archivo readme.md debe indicar a los lectores lo que aprenden a través de este ejemplo. El archivo readme.md debe contener también un vínculo al documento activo en el sitio de documentación de .NET. Para saber dónde un determinado archivo del repositorio se asigna a ese sitio, reemplace /docs en la ruta de acceso de repositorio por https://video2.skills-academy.com/dotnet.

El tema contendrá también vínculos al ejemplo. Se vincula directamente a la carpeta del ejemplo en GitHub.

Redacción de un nuevo ejemplo

Los ejemplos son programas y bibliotecas completos diseñados para su descarga. Puede que abarquen un ámbito reducido, pero muestran conceptos de una manera que permite a los usuarios explorar y experimentar por su cuenta. Las instrucciones de los ejemplos aseguran la descarga y la exploración para los lectores. Examine los ejemplos de Parallel LINQ (PLINQ) como muestra de cada una de las instrucciones.

1. El ejemplo debe formar parte de un proyecto que admita la compilación. Siempre que sea posible, los proyectos se deben compilar en todas las plataformas compatibles con .NET Core. Las excepciones son los ejemplos en los que se describe una característica o herramienta concreta de la plataforma.

2. El ejemplo se debe ajustar al estilo de código del entorno de ejecución para mantener la coherencia.

   Además, preferimos el uso de métodos static en lugar de métodos de instancia cuando se ilustre algo que no requiera la creación de instancias de un objeto nuevo.

3. En el ejemplo se debe incluir el control de excepciones adecuado. Debe controlar todas las excepciones que es probable que se inicien en el contexto del ejemplo. Por ejemplo, en un ejemplo en el que se llame al método Console.ReadLine para recuperar la entrada del usuario, se debe usar el control de excepciones adecuado cuando la cadena de entrada se pase como argumento a un método. De forma similar, si en el ejemplo se espera que se no pueda llamar a un método, se debe controlar la excepción resultante. Controle siempre las excepciones específicas iniciadas por el método, en lugar de las de la clase base como Exception o SystemException.

Para crear un ejemplo:

1. Abra una incidencia o agregue un comentario a una incidencia existente en la que esté trabajando.

2. Escriba el tema que explique los conceptos descritos en el ejemplo (por ejemplo: docs/standard/linq/where-clause.md).

3. Escriba el ejemplo (por ejemplo: WhereClause-Sample1.cs).

4. Cree un archivo Program.cs con un punto de entrada Main en el que se llame a los ejemplos. Si ya hay uno, agregue la llamada al ejemplo:

   public class Program
   {
       public void Main(string[] args)
       {
           WhereClause1.QuerySyntaxExample();
   
           // Add the method syntax as an example.
           WhereClause1.MethodSyntaxExample();
       }
   }
   

Los fragmentos de código o ejemplos de .NET se compilan mediante la CLI de .NET, que se puede instalar con el SDK de .NET Core. Para compilar y ejecutar el ejemplo:

1. Vaya a la carpeta de ejemplo y compile para comprobar los errores:

   dotnet build
   

2. Ejecute el ejemplo:

   dotnet run
   

3. Agregue un archivo readme.md al directorio raíz del ejemplo.

   Debe incluir una breve descripción del código y enviar a los usuarios al artículo en el que se hace referencia al ejemplo. La parte superior de readme.md debe tener los metadatos necesarios para el explorador de ejemplos. El bloque de encabezado debe contener los campos siguientes:

   ---
   name: "really cool sample"
   description: "Learn everything about this really cool sample."
   page_type: sample
   languages:
     - csharp
     - fsharp
     - vbnet
   products:
     - dotnet-core
     - dotnet
     - dotnet-standard
     - aspnet
     - aspnet-core
     - ef-core
   ---
   

   • La colección languages debe incluir solo los lenguajes disponibles para el ejemplo.
   • La colección products debe incluir solo los productos relevantes para el ejemplo.

Excepto donde se indique, todos los ejemplos se compilan desde la línea de comandos en todas las plataformas compatibles con .NET. Hay algunos ejemplos específicos de Visual Studio y requieren Visual Studio 2017 o una versión posterior. Además, en algunos ejemplos se describen características específicas de la plataforma, y requerirán una plataforma concreta. Otros ejemplos y fragmentos de código requerirán .NET Framework y se ejecutarán en plataformas Windows, y necesitarán el paquete de desarrollador para la versión de Framework de destino.

La experiencia interactiva de C#

En todos los ejemplos incluidos en un artículo se usa una etiqueta de idioma para indicar el idioma de origen. Los pequeños fragmentos de código de C# pueden usar la etiqueta de idioma csharp-interactive para especificar un fragmento de código de C# que se ejecute en el navegador. Los fragmentos de código insertados se utiliza la etiqueta csharp-interactive; para los fragmentos incluidos a partir del origen, se usa la etiqueta code-csharp-interactive. Estos fragmentos de código muestran una ventana de código y una ventana de salida en el artículo. En la ventana de salida se mostrará cualquier resultado producido después de ejecutar el código interactivo una vez que el usuario haya ejecutado el fragmento de código.

La experiencia interactiva de C# cambia nuestra forma de trabajar con los fragmentos de código. Los visitantes pueden ejecutar el fragmento de código para ver los resultados. Una serie de factores ayudan a determinar si el fragmento o el texto correspondiente deben incluir información sobre la salida.

Cuándo mostrar la salida esperada sin ejecutar el fragmento de código

• Los artículos dirigidos a principiantes deben ofrecer una salida para que los lectores pueden comparar la salida de su trabajo con la respuesta esperada.
• Los fragmentos de código en los que la salida es integral del tema deben mostrar esa salida. Por ejemplo, en los artículos sobre texto con formato se debe mostrar el formato de texto sin ejecutar el fragmento de código.
• Cuando el fragmento y la salida esperada sean breves, considere la posibilidad de mostrar la salida. Ahorra un poco de tiempo.
• Los artículos que describen cómo la referencia cultural actual o la referencia cultural invariable inciden en la salida deben explicar la salida esperada. El REPL (read–eval–print loop) interactivo se ejecuta en un host basado en Linux. La referencia cultural predeterminada y la referencia cultural invariable generan distintas salidas en los distintos sistemas operativos y máquinas. En el artículo se debe explicar la salida en los sistemas Windows, Linux y Mac.

Cuándo excluir del fragmento de código la salida esperada

• En el caso de los artículos en los que el fragmento genere una salida más grande, ello no se debe incluir en los comentarios. Oculta el código una vez ejecutado el fragmento.
• En los artículos en los que el fragmento describa un tema, pero la salida no sea esencial para entenderlo. Por ejemplo, código que ejecuta una consulta LINQ para explicar la sintaxis de consulta y luego muestra todos los elementos en la colección de salida.

Contribución a contenido que no está en inglés

En estos momentos no aceptamos contribuciones para contenido traducido automáticamente. En un esfuerzo por mejorar la calidad del contenido de MT, hemos realizado la transición a un motor neuronal de MT. Aceptamos y fomentamos las contribuciones de contenido de traducción humana (HT), que se usa para entrenar el motor neuronal de MT. Por lo tanto, con el tiempo, las contribuciones al contenido de HT mejorarán la calidad de HT y MT. Los temas traducidos de forma automática incluirán una declinación de responsabilidades en la que se hará constar que es posible que parte del contenido se haya traducido automáticamente. Asimismo, el botón Editar no se mostrará, ya que en este momento no se permite editar contenido.

Contrato de licencia de colaboración

Debe firmar el contrato de licencia de colaboración (CLA) de .NET Foundation antes de que la PR se combine. Se trata de un requisito único para los proyectos de .NET Foundation. Puede obtener más información sobre los contratos de licencia de colaboración (CLA) en Wikipedia.

El contrato: Contrato de licencia para el colaborador (CLA) de .NET Foundation

No tiene que firmar el contrato con antelación. Puede clonar, bifurcar y enviar la PR de la forma habitual. Cuando se haya creado la PR, un bot de CLA se encargará de clasificarla. Si el cambio es pequeño (por ejemplo, ha corregido un error ortográfico), la PR se etiqueta con cla-not-required. En caso contrario, se clasifica como cla-required. Cuando haya firmado el CLA, las solicitudes de incorporación de cambios actual y futuras se etiquetarán como cla-signed.