From efc429a7232cec270f033626c97f48647a6c4167 Mon Sep 17 00:00:00 2001 From: Bertocq Date: Fri, 18 Aug 2017 20:02:54 +0200 Subject: [PATCH 1/5] Add Contributing guidelines in english and spanish --- docs/CONTRIBUTING.md | 58 +++++++++++++++++++++++++++++++++++++++ docs/CONTRIBUTING_ES.md | 60 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/CONTRIBUTING_ES.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 000000000..be1f2139a --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,58 @@ +# Contributing + +We appreciate you want to help us by contributing to [Consul](https://github.com/consul/consul)'s Documentation. Here's a guide we made describing how to contribute changes to the project. + +## Code of conduct + +The core team members and the project's community adopts an inclusive Code of Conduct that you can read in the [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) file. + +## Reporting an issue and communications + +The prefered way to report any missing piece of information is [opening an issue in the project's Github repo](https://github.com/consul/docs/issues/new). For more informal communication, contact us through [consul's gitter](https://gitter.im/consul/consul) + +Before doing it, **please take some time to check the [existing issues](https://github.com/consul/docs/issues) and make sure what you are about to report isn't already reported** by another person. In case someone else reported the same problem before or a similar one, and you have more details about it, you can write a comment in the issue page... a little more help can make a huge difference! + +In order to write a new issue, take into account these few tips to make it easy to read and comprehend: + +- Try to use a descriptive and to-the-point title. +- It's a good idea to include some sections -in case they're needed- such as: steps to reproduce the bug, expected behaviour/response, actual response or screenshots. +- Also it could be helpful to provide your operating system, browser version and installed plugins. + +## Resolving an issue + +[Issues in Consul Docs](https://github.com/consul/docs/issues) labeled with `PRs-welcome` are well defined tasks ready to be documented by whoever wants to do it. In the other hand, the `not-ready` label marks tasks not well defined yet or subject to an internal decision, so we recommend not to try to resolve them until the core maintainers come to a resolution. + +We suggest to follow these steps to keep a good track of the changes you're about to make: + +- First of all, add a comment to any existing issue that your changes will address and resolve/close. If the issue has already someone assigned it means that person may be solving it, ask nicely about it. +- If there is no issue open about the changes you're going to make, sometimes makes sense to open it to start a little debate about it with other contributors and maintainers before the real work starts. Sometimes it prevents that debate from happening on the Pull Request comments, when it may be too late to revert some parts of the work done. +- [Fork the project](https://help.github.com/articles/fork-a-repo/) using your github account. +- Create a feature branch based on the `master` branch. To make it easier to identify, you can name it with the issue number followed by a concise and descriptive name (e.g. `123-fix_proposals_link`). +- Work in your branch committing there your changes. +- Once you've finished, send a **pull request** to the [Consul Docs repository](https://github.com/consul/docs/) describing your solution to help us understand it. It's also important to tell what issue you're addressing, so specify it in the pull request description's first line (e.g. `Fixes #123`). +- Core maintainers will review your PR and suggest changes if necessary. If everything looks good, your changes will be merged :) + +> **Working on your first Pull Request?** You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github). + +## How to contribute from your computer + +### Gitbooks + +This documentation is hosted online at [Gitbook](https://www.gitbook.com) for free, and its composed by [Markdown](https://es.wikipedia.org/wiki/Markdown) text files. Markdown its a lightweight markup language to give style to paragraphs, lists, etc... Check [Gitbook's Markdown syntax guide](https://toolchain.gitbook.com/syntax/markdown.html) + +To visualize on your browser how your changes would look you can use [https://github.com/GitbookIO/gitbook](https://github.com/GitbookIO/gitbook) to start a localhost server that will render the documentation. + +### Markdown Linter + +To maintain Markdown syntax consistency we use [Markdown Linter](https://github.com/markdownlint/markdownlint) and a `.mdlrc` file that holds its configuration on the project's root directory. + +To check your changes have no linting issues you first have to install the tool with `gem install mdl` and then execute it with `mdl .` + +## Other ways of contributing + +We'll appreciate any kind of contribution to Consul Docs. Even if you can't contribute to it writing new docs, you still can: + +- Create issues to notify the project owners with as much information as you can provide about anything wrong/missing you see, and someone will take care of it as soon as possible. +- Help translate existing documentation into a language that you master well enough. + +Gracias! ❤️❤️❤️ diff --git a/docs/CONTRIBUTING_ES.md b/docs/CONTRIBUTING_ES.md new file mode 100644 index 000000000..109ebd832 --- /dev/null +++ b/docs/CONTRIBUTING_ES.md @@ -0,0 +1,60 @@ +# Contribuciones + +Te agradecemos que quieras colaborar contribuyendo a la Documentación de [Consul](https://github.com/consul/consul). Aquí tienes una guía donde consultar cómo sugerir cambios y mejoras al proyecto. + +## Código de Conducta + +Los miembros del proyecto y la comunidad de personas que contribuyen a él se adhieren a un código de conducta que se puede consultar en el archivo [CODE_OF_CONDUCT_ES.md](CODE_OF_CONDUCT_ES.md). + +## Reporte de incidencias y comunicación + +Si has visto alguna sección incompleta o ausente, te animamos a [abrir una incidencia en el repositorio de Documentación de Consul](https://github.com/consul/docs/issues/new). + +Para comunicaciones más informales, contacta con nosotros a través del [gitter de consul](https://gitter.im/consul/consul) + +Antes de hacerlo, **por favor tómate un tiempo para comprobar los [issues ya existentes](https://github.com/consul/dics/issues) y asegúrate de que lo que estás a punto de reportar no ha sido reportado previamente** por otra persona. De ser así, si tienes más detalles acerca de la incidencia puedes escribir un comentario en la página ‑¡un poco de ayuda puede marcar una gran diferencia! + +Para escribir un nuevo issue, ten en cuenta estas recomendaciones para hacerlo más fácil de leer y comprender: + +- Intenta usar un título descriptivo. +- Es buena idea incluir algunas secciones -en caso de que sean necesarias- como los pasos para reproducir el error, el comportamiento o respuesta que cabría esperar, la respuesta que devuelve o capturas de pantalla. +- También puede ser de ayuda incluir en la descripción tu sistema operativo, versión del navegador que usaste y posibles plugins instalados. + +## Resolver incidencias + +[Las incidencias en los Docs](https://github.com/consul/docs/issues) con la etiqueta `PRs-welcome` son tareas bien definidas que están listas para ser resueltas por cualquiera que se ofrezca a ello. Por otra parte, la etiqueta `not-ready` indica las tareas o cambios que aún están pendientes de concretar, por lo que recomendamos no intentar resolverlos hasta que los/as miembros/as del proyecto lleguen a una resolución. + +Te sugerimos seguir los siguientes pasos para facilitar el seguimiento de los cambios que vayas a hacer: + +- Primero, añade un comentario en la incidencia para notificar que vas resolverlo. Si el issue tiene a alguien asignado significa que ya hay alguien encargado de él. +- Si no existe una incidencia para la tarea que vas a resolver, puede ser una buena idea crearla para hablar en la página de la incidencia con el resto de la comunidad acerca de como afrontar la tarea. A veces ayuda a prevenir que el debate se produzca en la revisión del Pull Request, y la sensación de haber dedicado tiempo en trabajo en vano. +- Crea un fork del proyecto. +- Crea una rama de funcionalidad basada en la rama `master`. Para identificarla más fácilmente, puedes nombrarla con el número de incidencia seguido de un nombre conciso y descriptivo (por ejemplo: `123-fix_proposals_link`). +- Desarrolla los cambios haciendo commits en tu nueva rama. +- Cuando hayas terminado, envía un **pull request** al [repositorio de Consul](https://github.com/consul/docs/) describiendo la solución que propones para ayudarnos a entenderlo. También es importante que especifiques qué incidencia estás resolviendo al principio de la descripción del PR (por ejemplo, `Fixes #123`). +- El equipo de Consul revisará tu PR y podrá sugerir cambios si son necesarios. Una vez esté todo bien, tus cambios serán introducidos en el proyecto :) + +> **¿Es tu primer Pull Request?** Puedes aprender cómo contribuir a un proyecto en Github siguiendo los tutoriales [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) (en inglés). + +## Cómo contribuir desde tu ordenador + +### Gitbooks + +Esta documentación se aloja online en [Gitbook](https://www.gitbook.com) de forma gratuita, y está formada de ficheros de texto [Markdown](https://es.wikipedia.org/wiki/Markdown). Markdown es un lenguage de marcado sencillo para dar estilo a párrafos, listas etc... Consulta [la guía de Gitbook sobre Markdown](https://toolchain.gitbook.com/syntax/markdown.html) + +Para visualizar en tu navegador como se verían tus cambios puedes usar [https://github.com/GitbookIO/gitbook](https://github.com/GitbookIO/gitbook) para levantar un servidor local que sirva la documentación. + +### Markdown Linter + +Para mantener la consistencia en la sintaxis de ficheros Markdown este proyecto usa [Markdown Linter](https://github.com/markdownlint/markdownlint) junto a un fichero de configuración `.mdlrc` en el directorio raiz. + +Para usarla instala la herramienta con `gem install mdl` y ejecuta después `mdl .` + +## Otras formas de contribuir + +Apreciaremos cualquier tipo de contribución a la Documentación de Consul. Incluso si no puedes contribuir a escribir nuevas secciones, puedes: + +- Crea una incidencia para notificar al resto de contribuidores con toda la información posible sobre lo que falta o esta incorrecto. +- Ayuda a traducir documentación existente a un idioma que domines suficientemente. + +Gracias! ❤️❤️❤️ From 96a8017ee713077c1e53dee8246ce37652d939e8 Mon Sep 17 00:00:00 2001 From: Bertocq Date: Fri, 18 Aug 2017 20:03:01 +0200 Subject: [PATCH 2/5] Add code of conduct in spanish --- docs/CODE_OF_CONDUCT_ES.md | 46 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/CODE_OF_CONDUCT_ES.md diff --git a/docs/CODE_OF_CONDUCT_ES.md b/docs/CODE_OF_CONDUCT_ES.md new file mode 100644 index 000000000..8153ebcba --- /dev/null +++ b/docs/CODE_OF_CONDUCT_ES.md @@ -0,0 +1,46 @@ +# Código de Conducta convenido para Contribuyentes + +## Nuestro compromiso + +En el interés de fomentar una comunidad abierta y acogedora, nosotros como contribuyentes y administradores nos comprometemos a hacer de la participación en nuestro proyecto y nuestra comunidad una experiencia libre de acoso para todos, independientemente de la edad, dimensión corporal, discapacidad, etnia, identidad y expresión de género, nivel de experiencia, nacionalidad, apariencia física, raza, religión, identidad u orientación sexual. + +## Nuestros estándares + +Ejemplos de comportamiento que contribuyen a crear un ambiente positivo: + +* Uso de lenguaje amable e inclusivo +* Respeto a diferentes puntos de vista y experiencias +* Aceptación de críticas constructivas +* Enfocarse en lo que es mejor para la comunidad +* Mostrar empatía a otros miembros de la comunidad + +Ejemplos de comportamiento inaceptable por participantes: + +* Uso de lenguaje o imágenes sexuales y atención sexual no deseada +* Comentarios insultantes o despectivos (*trolling*) y ataques personales o políticos +* Acoso público o privado +* Publicación de información privada de terceros sin su consentimiento, como direcciones físicas o electrónicas +* Otros tipos de conducta que pudieran considerarse inapropiadas en un entorno profesional. + +## Nuestras responsabilidades + +Los administradores del proyecto son responsables de clarificar los estándares de comportamiento aceptable y se espera que tomen medidas correctivas y apropiadas en respuesta a situaciones de conducta inaceptable. + +Los administradores del proyecto tienen el derecho y la responsabilidad de eliminar, editar o rechazar comentarios, *commits*, código, ediciones de documentación, *issues*, y otras contribuciones que no estén alineadas con este Código de Conducta, o de prohibir temporal o permanentemente a cualquier colaborador cuyo comportamiento sea inapropiado, amenazante, ofensivo o perjudicial. + +## Alcance + +Este código de conducta aplica tanto a espacios del proyecto como a espacios públicos donde un individuo esté en representación del proyecto o comunidad. Ejemplos de esto incluye el uso de la cuenta oficial de correo electrónico, publicaciones a través de las redes sociales oficiales, o presentaciones con personas designadas en eventos *online* u *offline*. La representación del proyecto puede ser clarificada explicitamente por los administradores del proyecto. + +## Aplicación + +Ejemplos de abuso, acoso u otro tipo de comportamiento inaceptable puede ser reportado al equipo del proyecto en consul@madrid.es. Todas las quejas serán revisadas e investigadas, generando un resultado apropiado a las circunstancias. El equipo del proyecto está obligado a mantener confidencialidad de la persona que reportó el incidente. Detalles específicos acerca de las políticas de aplicación pueden ser publicadas por separado. + +Administradores que no sigan o que no hagan cumplir este Código de Conducta pueden ser eliminados de forma temporal o permanente del equipo administrador. + +## Atribución + +Este Código de Conducta es una adaptación del [Contributor Covenant][homepage], versión 1.4, disponible en [http://contributor-covenant.org/version/1/4/es/][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/es/ From 19c3bde1eba2771ba732273cf67c9a1ef830fc99 Mon Sep 17 00:00:00 2001 From: Bertocq Date: Fri, 18 Aug 2017 19:55:06 +0200 Subject: [PATCH 3/5] Add MarkDownLinter basic config file --- docs/.mdlrc | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/.mdlrc diff --git a/docs/.mdlrc b/docs/.mdlrc new file mode 100644 index 000000000..5071bdb6d --- /dev/null +++ b/docs/.mdlrc @@ -0,0 +1 @@ +rules "MD001", "MD002", "MD003", "MD004", "MD005", "MD006", "MD007", "MD008", "MD009", "MD010", "MD011", "MD012", "MD014", "MD015", "MD016", "MD017", "MD018", "MD019", "MD020", "MD021", "MD022", "MD023", "MD024", "MD025", "MD026", "MD027", "MD028", "MD029", "MD030", "MD031", "MD032", "MD033", "MD034", "MD035", "MD036", "MD037", "MD038", "MD039", "MD040", "MD041" From e5b1296ad859caecebca777a1c4516773cd7ff38 Mon Sep 17 00:00:00 2001 From: Bertocq Date: Fri, 18 Aug 2017 20:08:18 +0200 Subject: [PATCH 4/5] Add translation and documentation tasks to contribution guidelines --- docs/en/open_source/contributing.md | 6 +++++- docs/es/open_source/contributing.md | 6 +++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/en/open_source/contributing.md b/docs/en/open_source/contributing.md index 066c10cdd..bb36b5338 100644 --- a/docs/en/open_source/contributing.md +++ b/docs/en/open_source/contributing.md @@ -31,4 +31,8 @@ We suggest to follow these steps to keep a good track of the changes you're abou ## Other ways of contributing -We'll appreciate any kind of contribution to Consul. Even if you can't contribute to it coding, you still can create issues to notify the project owners with as much information as you can provide about anything wrong you see, and someone will take care of it as soon as possible. +We'll appreciate any kind of contribution to Consul. Even if you can't contribute to it coding, you still can: + +- Create issues about any problem or error you've encountered +- Help translate the platform to other languages you master at [Consul's Crowdin](https://crwd.in/consul) +- Help with [Consul's documentation](https://github.com/consul/docs) diff --git a/docs/es/open_source/contributing.md b/docs/es/open_source/contributing.md index 9827bd47b..7d32ecc12 100644 --- a/docs/es/open_source/contributing.md +++ b/docs/es/open_source/contributing.md @@ -30,4 +30,8 @@ Te sugerimos seguir los siguientes pasos para facilitar el seguimiento de los ca ## Otras formas de contribuir -Agradecemos cualquier tipo de contribución a Consul. Incluso si no puedes contribuir al código del proyecto, puedes crear issues acerca de cualquier problema o error que hayas encontrado, y alguien se encargará de resolverlo a la mayor brevedad posible. +Agradecemos cualquier tipo de contribución a Consul. Incluso si no puedes contribuir al código del proyecto, puedes: + +- Crear issues sobre cualquier problema o error que hayas encontrado +- Ayudar a traducir la plataforma a otros idiomas que domines en el proyecto de [Consul en Crowdin](https://crwd.in/consul) +- Ayudar con la [documentación de Consul](https://github.com/consul/docs) From 2298d913b9f6a1309b72129ea4e2e938d66caf10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=ADa=20Checa?= Date: Fri, 18 Aug 2017 20:26:50 +0200 Subject: [PATCH 5/5] Minor changes Added period after list elements --- docs/en/open_source/contributing.md | 6 +++--- docs/es/open_source/contributing.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/en/open_source/contributing.md b/docs/en/open_source/contributing.md index bb36b5338..80492952f 100644 --- a/docs/en/open_source/contributing.md +++ b/docs/en/open_source/contributing.md @@ -33,6 +33,6 @@ We suggest to follow these steps to keep a good track of the changes you're abou We'll appreciate any kind of contribution to Consul. Even if you can't contribute to it coding, you still can: -- Create issues about any problem or error you've encountered -- Help translate the platform to other languages you master at [Consul's Crowdin](https://crwd.in/consul) -- Help with [Consul's documentation](https://github.com/consul/docs) +- Create issues about any problem or error you've encountered. +- Help translate the platform to other languages you master at [Consul's Crowdin](https://crwd.in/consul). +- Help with [Consul's documentation](https://github.com/consul/docs). diff --git a/docs/es/open_source/contributing.md b/docs/es/open_source/contributing.md index 7d32ecc12..92fe1bbdc 100644 --- a/docs/es/open_source/contributing.md +++ b/docs/es/open_source/contributing.md @@ -32,6 +32,6 @@ Te sugerimos seguir los siguientes pasos para facilitar el seguimiento de los ca Agradecemos cualquier tipo de contribución a Consul. Incluso si no puedes contribuir al código del proyecto, puedes: -- Crear issues sobre cualquier problema o error que hayas encontrado -- Ayudar a traducir la plataforma a otros idiomas que domines en el proyecto de [Consul en Crowdin](https://crwd.in/consul) -- Ayudar con la [documentación de Consul](https://github.com/consul/docs) +- Crear issues sobre cualquier problema o error que hayas encontrado. +- Ayudar a traducir la plataforma a otros idiomas que domines en el proyecto de [Consul en Crowdin](https://crwd.in/consul). +- Ayudar con la [documentación de Consul](https://github.com/consul/docs).