45 problemas de Github que se deben y no se deben hacer -

PorJason Chen es

Muchos proyectos de código abierto utilizan Github Issues como principal medio de comunicación y herramienta para la gestión de tareas. Su apertura y disponibilidad es una de sus mayores fortalezas. Pero algunos consejos rápidos lo convertirán en un participante mucho más responsable, especialmente en proyectos grandes.

Problemas de informes

Abra un problema para un problema.

Abra dos números para dos números.

No agregue “Oh, por cierto, aquí hay otro problema que noté” a un problema no relacionado .

Mantenga los hechos y las opiniones separados, idealmente los hechos primero y las opiniones al final. Los datos incluyen detalles de la plataforma, pasos de reproducción y lo que ha probado. Las opiniones incluyen especulaciones sobre causas fundamentales que no se han investigado.

Sea específico, especialmente en los pasos de reproducción. En lugar de la instrucción: “escriba un texto”, sea claramente específica con la instrucción: “Escriba 'Prueba'”. El error podría tener que ver con la tecla Mayús y no será reproducido por otras personas que presionen repetidamente adsfasdfadsfasd. Esto no es un hecho teórico: la subespecificación sigue siendo una de las razones más comunes por las que los problemas válidos se cierran por no ser reproducibles.

Reduzca los pasos de reproducción al mínimo necesario para demostrar su problema. Hace que sea más fácil para otros ayudar y la selección a menudo revela relaciones relevantes.

Especifique la plataforma o el entorno, normalmente el navegador y el sistema operativo. Esto importa mucho más de lo que uno podría pensar.

No incluyas plataformas en las que no hayas probado. Es suficiente que sea un error legítimo si sólo una plataforma compatible se ve afectada. Los falsos positivos solo invitarán al despido si otros no pueden reproducir en una plataforma en la que usted no realizó la prueba, pero que aún está incluido en el informe de error.

Intente reproducir su problema constantemente, en un ambiente limpio. Comience con la parte consistente.

Informe un problema recurrente incluso sin pasos de reproducción si no puede identificarlo, después de un gran esfuerzo. A veces esto está bien con suficientes detalles sobre el entorno y el contexto, para que otros puedan ayudar a llenar los vacíos.

Utilice viñetas, dos puntos e incluso cláusulas incompletas cuando sea apropiado. “Plataforma: Chrome/OSX, no probado en otros lugares” transmite tanta información como su equivalente gramaticalmente correcto.

Dedique más tiempo a escribir un buen título. Debe ser breve pero descriptivo, similar al enfoque de escribir un buen mensaje de confirmación. Los colaboradores suelen ver los problemas en la vista de lista, donde solo se muestran los títulos y los problemas con títulos incorrectos se ignorarán.

Intente resolver o solucionar el problema y proporcione detalles de lo que intentó, incluso si no funcionó .

Do answer other people’s questions if you know the answer. Responding to questions is not a privilege reserved for just maintainers. Earnestly helping others is what open source is about!

Do not guess if you do not know the answer to someone’s question. Signals are helpful, not noise, wherever either comes from.

Do follow theissue template if one is provided.

Requesting Features

Do be specific in describing what you want to be added and how it would solve a problem you are facing.

Do not open an Issue with just “make X better” or “improve X”.

Do open an issue for a feature request with “Make X better by adding Y because Z”.

Do propose an API spec, even if it has obvious shortcomings. This starts the conversation with concrete details, and progress can be made from there.

Do not confuse feature size with project fit. Fit is determined first, then implementation. Some fitting features will take a long time to implement because they are large. But no unfit features should be implemented no matter how easy.

Do not open hypothetical feature requests. If you do not personally need the feature or have the use case, you are not qualified to recommend the solution.

Do use thereaction feature, instead of commenting “+1” in 2016. A large group of open source maintainers almostrage quit over this and Github finally built it. Now use it!

Do close feature requests you no longer need. If someone else has the same request, they can open a separate issue more focused on their needs.

Pull Requests

Do submit one pull request to address one issue.

Do submit two pull request to address two issues.

Do not tack on a minor whitespace or semicolon changes in unrelated commits or Pull Requests, even if the minor change is correct. Make a dedicated commit or Pull Request instead.

Do read thecontributing.md guideline if one is linked.

Do submit pull requests for typo fixes in documentation or comments. This is the easiest and most welcome way to get your name added to the contributor list.

Do not submit a large surprise Pull Request. Discuss the need for it and the merits of your approach first, probably in a Github Issue or the project discussion forum or mailing list.

Do not be surprised or get upset when you ignore the above and your Pull Request gets closed.

Do not expect all Pull Requests to lead to being merged.

Do not expect others to coach you through your Pull Request. It happens when time permits but expecting it is misguided entitlement. Pick an easier way to contribute if you get stuck.

Do include tests with your Pull Request.

Do follow the style guide if one is provided. If none is, use the existing codebase as a guideline.

Do not confuse implementation cost with maintenance cost. The latter is far more expensive and healthy projects take long term considerations seriously.

Being a Decent Human Being

Do search through existing issues to see if yours has already been reported. It might even have already been resolved!

Do flag other Issues as a duplicate. Sometimes it is hard to find the right search terms in Github Issues and duplicates get created despite best intentions.

Do keep comments short, concise and on topic. High information density is essential for effective communication over a distributed and diverse landscape that is open source.

Do read the documentation. No one wants to have to show their ugly side on a bad day. Also known as RTFM™.

Do email the maintainers if you work for a giant company with an annoying legal department and willabandon using the project without private assistance.

Do not email the maintainers to draw attention to an issue you reported.

Do enjoy the benefits of permissive open source software “free of charge… without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software…” guaranteed by thelicense.

Do not ignore the all caps part: “THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED…” Open source is largely a volunteer effort. Any additional help that volunteer contributors provide is additional.

Do be charitable with your interpretation of others’ words. For example, reasonable interpretations of “What do you not understand?” include a condescending insult or hurried clarification attempt. But the most charitable interpretation is that it is an open ended invitation to be a data point used to improve the documentation. With global diversity of personalities and cultures participating in open source and the low emotional density of written text, always default to the most charitable interpretation of others’ words.

What are some of your dos and don’ts that I missed? Let me know in the comments. Also follow@jhchen to hear more about open source and startups!

Thanks to@avitaloliver,@shapiro, and@timabbott for reviewing drafts of this post.

About Jason Chen

Jason is the author and core maintainer ofQuill. He previously founded Stypi, a collaborative code editor that was later acquired by Salesforce. He is fascinated with the dissemination and retention of knowledge and ideas.

jasonchen.mejhchenPosts