├── .github ├── FUNDING.yml ├── ISSUE_TEMPLATE.md ├── PULL_REQUEST_TEMPLATE.md ├── workflows │ └── deploy.yml ├── CONTRIBUTING.md └── CODE_OF_CONDUCT.md ├── src ├── favicon.ico ├── images │ ├── github-contributing-file.png │ └── github-syntax-highlighting.png ├── dont │ ├── dont-god-commit-es.adoc │ ├── dont-god-pull-request.adoc │ ├── dont-god-pull-request-es.adoc │ ├── dont-big-bang-project.adoc │ ├── dont-god-commit.adoc │ ├── dont-weakest-dependency.adoc │ ├── dont-big-bang-project-es.adoc │ ├── dont-weakest-dependency-es.adoc │ ├── dont-cv-driven-development.adoc │ └── dont-cv-driven-development-es.adoc ├── do │ ├── do-optimal-time.adoc │ ├── do-optimal-time-es.adoc │ ├── do-review.adoc │ ├── do-plan-ahead.adoc │ ├── do-always-respond.adoc │ ├── do-little-and-often.adoc │ ├── do-plan-ahead-es.adoc │ ├── do-review-es.adoc │ ├── do-code-block.adoc │ ├── do-milestone.adoc │ ├── do-not-enough-time.adoc │ ├── do-release.adoc │ ├── do-always-respond-es.adoc │ ├── do-little-and-often-es.adoc │ ├── do-not-enough-time-es.adoc │ ├── do-milestone-es.adoc │ ├── do-codebase-improvements.adoc │ ├── do-code-block-es.adoc │ ├── do-always-respond-fil.adoc │ ├── do-prototyping.adoc │ ├── do-code-block-fil.adoc │ ├── do-codebase-improvements-es.adoc │ ├── do-release-es.adoc │ ├── do-prototyping-es.adoc │ ├── do-codebase-improvements-fil.adoc │ ├── do-branching.adoc │ ├── do-labels-es.adoc │ ├── do-branching-es.adoc │ ├── do-fail-fast.adoc │ ├── do-labels.adoc │ ├── do-fail-fast-es.adoc │ ├── do-issue-task.adoc │ ├── do-branching-fil.adoc │ ├── do-issue-task-es.adoc │ ├── do-accessible.adoc │ ├── do-accessible-es.adoc │ ├── do-accessible-fil.adoc │ ├── do-code-of-conduct.adoc │ ├── do-git-commit.adoc │ ├── do-contribution-file.adoc │ ├── do-automation.adoc │ ├── do-git-commit-es.adoc │ ├── do-code-of-conduct-es.adoc │ ├── do-contribution-file-es.adoc │ ├── do-explore-open-source-projects.adoc │ ├── do-github-template-files.adoc │ ├── do-code-of-conduct-fil.adoc │ ├── do-explore-open-source-projects-es.adoc │ ├── do-explore-open-source-projects-fil.adoc │ ├── do-automation-es.adoc │ ├── do-contribution-file-fil.adoc │ ├── do-pull-request.adoc │ ├── do-github-template-files-es.adoc │ ├── do-readme.adoc │ ├── do-automation-fil.adoc │ ├── do-readme-es.adoc │ ├── do-pull-request-es.adoc │ ├── do-licensing.adoc │ └── do-licensing-es.adoc ├── dont.adoc ├── dont-es.adoc ├── docinfo-footer.html ├── do.adoc ├── do-fil.adoc ├── do-es.adoc ├── index.adoc ├── index-es.adoc ├── index-fil.adoc └── appendix.adoc ├── .devcontainer ├── Dockerfile └── devcontainer.json ├── LICENSE ├── Makefile ├── CODE_OF_CONDUCT.md ├── README.md └── config └── pdf-theme.yml /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | # These are supported funding model platforms 2 | 3 | github: [eddiejaoude] 4 | -------------------------------------------------------------------------------- /src/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/eddiejaoude/book-open-source-tips/HEAD/src/favicon.ico -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | 2 | | Type | Bug / Idea | 3 | | :--- | :--- | 4 | | Screenshot included? | yes / no | 5 | | Description | ... | 6 | -------------------------------------------------------------------------------- /src/images/github-contributing-file.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/eddiejaoude/book-open-source-tips/HEAD/src/images/github-contributing-file.png -------------------------------------------------------------------------------- /src/images/github-syntax-highlighting.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/eddiejaoude/book-open-source-tips/HEAD/src/images/github-syntax-highlighting.png -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | | Type | Bug Fix / New Feature | 2 | | :--- | :--- | 3 | | Screenshot | yes / no | 4 | | Description of changes | ... | 5 | -------------------------------------------------------------------------------- /src/dont/dont-god-commit-es.adoc: -------------------------------------------------------------------------------- 1 | === Commit de dios 2 | 3 | Los commits de dios o commits big bang son inútiles y confusos. Son terribles para ti y para la comunidad por demasiadas razones. 4 | 5 | TIP: Cada commit debe hacer sólo un ítem 6 | -------------------------------------------------------------------------------- /src/do/do-optimal-time.adoc: -------------------------------------------------------------------------------- 1 | === Optimal time - work when at your best 2 | 3 | People work better at different times of the day and night so find your most efficient and optimal time. Even if that is 11pm at night or 4am, try utilise your most productive time. 4 | -------------------------------------------------------------------------------- /src/dont.adoc: -------------------------------------------------------------------------------- 1 | include::dont/dont-big-bang-project.adoc[] 2 | 3 | include::dont/dont-god-commit.adoc[] 4 | 5 | include::dont/dont-god-pull-request.adoc[] 6 | 7 | include::dont/dont-cv-driven-development.adoc[] 8 | 9 | include::dont/dont-weakest-dependency.adoc[] 10 | -------------------------------------------------------------------------------- /src/dont-es.adoc: -------------------------------------------------------------------------------- 1 | include::dont/dont-big-bang-project-es.adoc[] 2 | 3 | include::dont/dont-god-commit-es.adoc[] 4 | 5 | include::dont/dont-god-pull-request-es.adoc[] 6 | 7 | include::dont/dont-cv-driven-development-es.adoc[] 8 | 9 | include::dont/dont-weakest-dependency-es.adoc[] 10 | -------------------------------------------------------------------------------- /src/do/do-optimal-time-es.adoc: -------------------------------------------------------------------------------- 1 | === Tiempo óptimo - trabaja en tu mejor momento 2 | 3 | Las personas trabajan mejor en diferentes momentos del día y la noche, así que intenta encontrar tu momento más eficiente y óptimo. Incluso si es a las 11pm en la noche o las 4am, trata de utilizar tu momento más productivo. 4 | -------------------------------------------------------------------------------- /src/do/do-review.adoc: -------------------------------------------------------------------------------- 1 | === Review 2 | 3 | Even if it is only you on the project, try to raise Pull Requests & get a friend to review it. This approach is invaluable as a second pair of eyes often picks up oversights. 4 | 5 | TIP: Even simple text changes might make sense to you but not to someone else. Review everything! 6 | -------------------------------------------------------------------------------- /src/do/do-plan-ahead.adoc: -------------------------------------------------------------------------------- 1 | === Plan ahead 2 | 3 | Create tasks today ready in preparation for tomorrow. There are two benefits of this, allowing you tomorrow to immediately hit the ground running and to digest the tasks overnight as you might make some final tweaks. 4 | 5 | TIP: Plan a little ahead, not too much as things will change 6 | -------------------------------------------------------------------------------- /src/do/do-always-respond.adoc: -------------------------------------------------------------------------------- 1 | === Always respond - Issue and Pull Request 2 | 3 | Always respond to Issue and Pull Request in a timely fashion, ideally within 24 hours (even if it is with a comment acknowledging you have at least read the issue & will respond fully at a later date). This manages expectations for when the contributor can expect a full response. 4 | -------------------------------------------------------------------------------- /src/do/do-little-and-often.adoc: -------------------------------------------------------------------------------- 1 | === Little and often 2 | 3 | Steady projects are not only more stable, but are generally more successful & are better for your health. Trying doing a little every day or week. 4 | 5 | Working frequently on your project gives your community confidence that you believe in your project & are in it for the long term not just that moment. 6 | -------------------------------------------------------------------------------- /src/do/do-plan-ahead-es.adoc: -------------------------------------------------------------------------------- 1 | === Planifica 2 | 3 | Crea tareas hoy en preparación para el mañana. Esto tiene dos beneficios, te permite en un futuro comenzar a trabajar de manera inmediata, y digerir las tareas por la noche cuando tal vez realices los últimos retoques. 4 | 5 | TIP: Planifica para un futuro próximo, no muy lejano, ya que las cosas pueden cambiar 6 | -------------------------------------------------------------------------------- /src/do/do-review-es.adoc: -------------------------------------------------------------------------------- 1 | === Revisión 2 | 3 | Incluso si eres sólo tú en el proyecto, intenta crear Pull Requests y pide a un amigo que lo revise. Esta aproximación es invaluable ya que un segundo par de ojos encuentra con frecuencia las omisiones. 4 | 5 | TIP: Incluso los cambios de texto simples pueden tener sentido para tí pero no para alguien más. ¡Revisa todo! 6 | -------------------------------------------------------------------------------- /src/dont/dont-god-pull-request.adoc: -------------------------------------------------------------------------------- 1 | === God Pull Request 2 | 3 | Similar to "god commit", god pull request are a bad idea. Reviewing god or big bang pull request are not only annoying & painful, but leave room for skim reviewing & therefore mistakes. A pull request should be a single feature. 4 | 5 | TIP: No one ever complained that a Pull Request was too small. 6 | -------------------------------------------------------------------------------- /src/do/do-code-block.adoc: -------------------------------------------------------------------------------- 1 | === Code block 2 | 3 | Use syntax highlighting within code blocks in documentation to make it easier to read. 4 | 5 | image::github-syntax-highlighting.png[caption="", role="thumb",title="GitHub syntax highlighting", alt="GitHub syntax highlighting", link="https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting"] 6 | -------------------------------------------------------------------------------- /src/do/do-milestone.adoc: -------------------------------------------------------------------------------- 1 | === GitHub Milestones 2 | 3 | Using *Milestones* not only gives you and your community visibility on the current goal and its progress, but also the future goals and what they contain. 4 | 5 | TIP: Align your *Release* versions with your *Milestones* 6 | 7 | .Related 8 | **** 9 | * link:index.html#_github_releases_tags[Release tips] 10 | **** 11 | -------------------------------------------------------------------------------- /src/do/do-not-enough-time.adoc: -------------------------------------------------------------------------------- 1 | === Not enough time 2 | 3 | We all have the same 24 hours in a day available to us. It's what you do with it that counts. Try to find a small amount of time per day, even 10 minutes when you are on the toilet - yes you heard me right "on the toilet". Multi tasking in that situation is possible, but trying to work while watching TV is very unproductive. 4 | -------------------------------------------------------------------------------- /src/do/do-release.adoc: -------------------------------------------------------------------------------- 1 | === GitHub Releases / Tags 2 | 3 | When you are happy with the work done so far, make a *Release* so your community knows, this is a stable version. In the *release notes*, include *change log*. 4 | 5 | TIP: Align your *Release* versions with your *Milestones* 6 | 7 | .Related 8 | **** 9 | * link:index.html#_github_milestones[Milestone tips] 10 | **** 11 | -------------------------------------------------------------------------------- /src/do/do-always-respond-es.adoc: -------------------------------------------------------------------------------- 1 | === Siempre responda - Issue y Pull Request 2 | 3 | Responda siempre a un Issue y Pull Request de manera oportuna, idealmente dentro de 24 horas (incluso si se trata de un comentario que confirma que al menos ha leído el problema y responderá completamente en 3 días). Esto maneja las expectativas de cuándo el contribuyente puede esperar una respuesta completa. 4 | -------------------------------------------------------------------------------- /src/do/do-little-and-often-es.adoc: -------------------------------------------------------------------------------- 1 | === Poco y frecuente 2 | 3 | Los proyectos constantes no sólo son más estables, sino que generalmente son más exitosos y mejores para tu salud. Intenta hacer un poco cada día de la semana. 4 | 5 | Trabajar frecuentemente en tu proyecto le brinda a tu comunidad certeza de que crees en tu proyecto y que estás en él a largo plazo y no solamente en ese momento. 6 | -------------------------------------------------------------------------------- /src/do/do-not-enough-time-es.adoc: -------------------------------------------------------------------------------- 1 | === Sin tiempo suficiente 2 | 3 | Todos tenemos las mismas 24 horas disponibles en el día para nosotros. Es lo que haces con eso lo que cuenta. Intenta encontrar un poco de tiempo cada día, incluso 10 minutos cuando estás en el baño - sí, oíste bien, "en el baño". Multi-tareas en esa situación es posible, pero intentar trabajar mientras miras TV es muy improductivo. 4 | -------------------------------------------------------------------------------- /src/do/do-milestone-es.adoc: -------------------------------------------------------------------------------- 1 | === Milestones de GitHub 2 | 3 | Usar *Milestones* (metas) no sólo te da a ti y a tu comunidad visibilidad del objetivo actual y su progreso, sino también de los objetivos futuros y su contenido. 4 | 5 | TIP: Alinea tus versiones *Release* con tus *Milestones* 6 | 7 | .Relacionado 8 | **** 9 | * link:index.html#_github_releases_tags[Consejos de publicaciones] 10 | **** 11 | -------------------------------------------------------------------------------- /src/do/do-codebase-improvements.adoc: -------------------------------------------------------------------------------- 1 | === Codebase improvements - Leave the codebase better than you found it 2 | 3 | Many code repositories (mostly Closed Source ones) go from bad to worse. On the other hand, Open Source projects tend to do the complete opposite due to it being in the public eye. Even the smallest of improvements add up and really help. 4 | 5 | TIP: No improvement is too small. Make it better. 6 | -------------------------------------------------------------------------------- /src/dont/dont-god-pull-request-es.adoc: -------------------------------------------------------------------------------- 1 | === Pull Request de dios 2 | 3 | Similar a los "commit de dios", los pull request de dios son una mala idea. Revisar pull request de dios o big bang no sólo es agobiante y laborioso, sino que además dan lugar a revisiones superficiales y por lo tanto errores. Un pull request debe ser una sola característica. 4 | 5 | TIP: Nunca nadie se quejó de que un Pull Request era muy pequeño. 6 | -------------------------------------------------------------------------------- /src/do/do-code-block-es.adoc: -------------------------------------------------------------------------------- 1 | === Bloque de código 2 | 3 | Utilice el resaltado de sintaxis dentro de los bloques de código en la documentación para que sea más fácil de leer. 4 | 5 | image::github-syntax-highlighting.png[caption="", role="thumb", title="Resaltado de sintaxis de Github", alt="Resaltado de sintaxis de Github", link="https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting"] 6 | -------------------------------------------------------------------------------- /src/do/do-always-respond-fil.adoc: -------------------------------------------------------------------------------- 1 | === Laging Tumugon - Issue at Pull Request 2 | 3 | Laging tumugon sa Issue at Pull Request sa napapanahong paraan, mas mainam kung ito'y sa loob ng 24 oras (kahit na ito'y sa pamamagitan ng komentong nagbibigay-alam ng pagtanggap o kahit man lang sa pagbasa ng isyu at ganap itong matutugunan sa 3 araw). Pinamamahalaan nito ang pag-asa sa kung kailan makakatanggap ng ganap na katugunan ang taga-ambag. 4 | -------------------------------------------------------------------------------- /src/do/do-prototyping.adoc: -------------------------------------------------------------------------------- 1 | === Prototyping - Get a prototype to your users quickly 2 | 3 | Get feedback as soon as possible. Get a quick and dirty prototypes in front of some of your users will give you instant feedback and direction. Remember to make it clear it is a prototype. 4 | 5 | TIP: When building a prototype, the technology is less important to choose for longevity but for speed & possibly to test out potential technology solution. 6 | -------------------------------------------------------------------------------- /src/do/do-code-block-fil.adoc: -------------------------------------------------------------------------------- 1 | === Bloke ng code 2 | 3 | Gumamit ng pag-highlight ng syntax sa loob ng mga bloke ng code sa dokumentasyon para mapadali ang pagbasa nito. 4 | 5 | image::github-syntax-highlighting.png[caption="Pag-highlight ng syntax sa Github", role="thumb", title="Pag-highlight ng syntax sa Github", alt="GitHub syntax highlighting", link="https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting"] 6 | -------------------------------------------------------------------------------- /src/do/do-codebase-improvements-es.adoc: -------------------------------------------------------------------------------- 1 | === Mejoras en la base de código: Deja la base de código mejor de lo que la encontraste 2 | 3 | Muchos repositorios de código (principalmente los de Código Cerrado) van de mal en peor. Por otro lado, los proyectos de Código Abierto tienden a ser todo lo contrario debido a que están en el ojo público. Incluso las mejoras más pequeñas suman y realmente ayudan. 4 | 5 | CONSEJO: Ninguna mejora es demasiado pequeña. Hazlo mejor. 6 | -------------------------------------------------------------------------------- /src/dont/dont-big-bang-project.adoc: -------------------------------------------------------------------------------- 1 | === Big bang project 2 | 3 | Don't try to complete the project in a manic weekend, then ignore it for the next year. This is not good for your health nor does it look good for your project from the community's view. 4 | 5 | TIP: Try to be consistent and do a little every week. Your thoughts and ideas will be better over time, this will prevent you from wasting time on redoing work when you get a light bulb moment a few days later. 6 | -------------------------------------------------------------------------------- /src/dont/dont-god-commit.adoc: -------------------------------------------------------------------------------- 1 | === God commit 2 | 3 | God commits or big bang commits are not good because they are difficul to understand and review, these can block pull requests. 4 | 5 | Also if a commit needs to be cherry picked in/out, then it makes it very difficult. 6 | 7 | For example if files are being reformatted, this should be done in 1 commit, not with other changes otherwise it is confusing. 8 | 9 | TIP: Each commit should do one single item 10 | -------------------------------------------------------------------------------- /src/do/do-release-es.adoc: -------------------------------------------------------------------------------- 1 | === Publicaciones / Etiquetas de GitHub 2 | 3 | Cuando estés conforme con el trabajo hecho, realiza una *Release* (publicación) para que tu comunidad sepa que es una versión estable. En las *release notes* (notas de la publicación), incluye *change log* (registro de cambios). 4 | 5 | TIP: Alinea tus versiones *Release* con tus *Milestones* 6 | 7 | .Relacionado 8 | **** 9 | * link:index.html#_github_milestones[Consejos de metas] 10 | **** 11 | -------------------------------------------------------------------------------- /src/do/do-prototyping-es.adoc: -------------------------------------------------------------------------------- 1 | === Prototipando - Consigue rápidamente un prototipo para tus usuarios 2 | 3 | Consigue feedback tan pronto como sea posible. Provee un prototipo rápido a tus usuarios para obtener feedback y dirección instantáneos. Recuerda dejar en claro que es un prototipo. 4 | 5 | TIP: Cuando construyes un prototipo, la tecnología que eliges es menos importante con respecto a la longevidad que a la rapidez y posibilidad de testear nuestra potencial solución tecnológica. 6 | -------------------------------------------------------------------------------- /src/dont/dont-weakest-dependency.adoc: -------------------------------------------------------------------------------- 1 | === Weakest Dependency 2 | 3 | Your project is only as good as your weakest dependency. Check the dependencies you include in your project before including them, look at their: 4 | 5 | - license 6 | - contribution activity 7 | - security 8 | - contributors 9 | 10 | TIP: Be aware of dependencies you include. It is great not to reinvent the wheel, there are usually a lot of choices available but make sure to do your research on the available libraries. 11 | -------------------------------------------------------------------------------- /src/dont/dont-big-bang-project-es.adoc: -------------------------------------------------------------------------------- 1 | === Poryecto Big bang 2 | 3 | No intentes completar todo el proyecto en un fin de semana maníaco, y luego ignorarlo por el próximo año. Esto no es bueno para tu salud y tampoco habla bien de tu proyecto desde el punto de vista de la comunidad. 4 | 5 | TIP: Intenta ser consistente y hacer un poco cada semana. Tus pensamientos e ideas irán mejorando con el tiempo, esto prevendrá que malgastes tu tiempo rehaciendo trabajo cuando tengas un momento de inspiración unos días más tarde. 6 | -------------------------------------------------------------------------------- /src/dont/dont-weakest-dependency-es.adoc: -------------------------------------------------------------------------------- 1 | === Dependencia más débil 2 | 3 | Tu proyecto es tan bueno como tu dependencia más débil. Revisa las dependencias que incluyes en tu proyecto antes de incluirlas, mira sus: 4 | 5 | - licencia 6 | - actividad de contribución 7 | - seguridad 8 | - colaboradores 9 | 10 | TIP: Sé consciente de las dependencias que incluyes. Es estupendo no reinventar la rueda, usualmente hay un montón de opciones disponibles pero asegúrate de realizar tu investigación acerca de las librerías disponibles. 11 | -------------------------------------------------------------------------------- /src/do/do-codebase-improvements-fil.adoc: -------------------------------------------------------------------------------- 1 | === Mga pagpapabuti sa codebase - Iwan ang codebase ng mas mabuti kaysa ng natagpuan mo ito 2 | 3 | Maraming mga imbakan ng code (kadalasan ang mga Closed Source) ang pumupunta galing sa masama patungo sa mas masama. Sa isang banda, ang mga proyektong Open Source ay posibleng magawi sa ganap na kabaligtaran nito dahil ito'y nakikita ng publiko. Kahit ang pinakamaliit na mga pagpapabuti ay nakakapagdagdag at talagang nakakatulong. 4 | 5 | TIP: Walang pagpapabuti na napakaliit. Gawin itong mas mabuti. 6 | -------------------------------------------------------------------------------- /src/dont/dont-cv-driven-development.adoc: -------------------------------------------------------------------------------- 1 | === CV Driven Development 2 | 3 | Most of us have heard of Test Driven Development (TDD). Do not fall in to the trap of CV Driven Development (CVDD). It is good to push your skills with new technology but do a little at a time to reduce the risk. Do not try every new technology you want to learn on the same project, this is very high risk, with the mostly likely outcome of little result & therefore frustration. 4 | 5 | TIP: Approximately 10 - 20% of new technology per project is a good, safe & exciting amount. 6 | -------------------------------------------------------------------------------- /src/docinfo-footer.html: -------------------------------------------------------------------------------- 1 |

2 | English | 3 | Spanish | 4 | Filipino 5 |
6 | 7 | PDF Download 8 | 9 |
10 | 11 | v{version} 12 | 13 |

14 | 15 | 16 | -------------------------------------------------------------------------------- /src/do/do-branching.adoc: -------------------------------------------------------------------------------- 1 | === Branching 2 | 3 | Branching is important when working with a team, and even more important when working with a wider team you don't even know yet. 4 | 5 | Protect your mainline branch (usually `master` or `develop`) and everything must go via a feature branch and a **Pull Request**. This should be the same for everyone, public contributors and approved maintainers. 6 | 7 | TIP: There are many branching strategies, one example is *Gitflow*, many people use part of http://nvie.com/posts/a-successful-git-branching-model/[Gitflow]. 8 | 9 | .Related 10 | **** 11 | * link:index.html#_pull_requests[Pull Requests] 12 | **** 13 | -------------------------------------------------------------------------------- /src/do/do-labels-es.adoc: -------------------------------------------------------------------------------- 1 | === Etiquetas de GitHub (Labels) 2 | 3 | Éstas son realmente útiles por varias razones: 4 | 5 | - Ayudan a la gente a filtrar sus resultados, por ejemplo, por `defecto`, `idea`, etc 6 | - Si las personas quieren contribuir a tu proyecto, una etiqueta que manifiesta `help needed` (ayuda requerida) va a sobresalir 7 | - Nivel de dificultad. Los contribuyentes pueden filtrar por el nivel de dificultad en el cual se sienten cómodos 8 | 9 | TIP: Pon diferentes etiquetas pero no te vuelvas loco, entre 10-20 está bien 10 | 11 | .Relacionado 12 | **** 13 | * link:index.html#_github_issue_task[Consejos de Issues & Tasks] 14 | **** 15 | -------------------------------------------------------------------------------- /src/dont/dont-cv-driven-development-es.adoc: -------------------------------------------------------------------------------- 1 | === Desarrollo guiado por CV 2 | 3 | Muchos de nosotros hemos escuchado acerca del Desarrollo guiado por pruebas o Test Driven Development (TDD). No caigas en la trampa del Desarrollo guiado por CV o CV Driven Development (CVDD). Es bueno aumentar tus habilidades con nuevas tecnologías pero haz poco a la vez para reducir el riesgo. No pruebes cada nueva tecnología que deseas aprender en el mismo proyecto, esto es de muy alto riesgo, con la conclusión más probable de un pobre resultado y, por consiguiente, frustración. 4 | 5 | TIP: Aproximadamante entre un 10 - 20% de nuevas tecnologías por proyecto es una buena, segura y excitante cantidad. 6 | -------------------------------------------------------------------------------- /src/do/do-branching-es.adoc: -------------------------------------------------------------------------------- 1 | === Ramificaciones 2 | 3 | La ramificación es importante cuando se trabaja con un equipo, y aún más importante cuando se trabaja con un equipo más amplio que aún no se conoce. 4 | 5 | Proteja su rama principal (generalmente `master` o `develop`) y todo debe ir a través de una rama y un **Pull Request**. Esto debería ser igual para todos, contribuyentes públicos y mantenedores aprobados. 6 | 7 | CONSEJO: Existen muchas estrategias de ramificación, un ejemplo es *Gitflow*, muchas personas usan parte de http://nvie.com/posts/a-successful-git-branching-model/[Gitflow]. 8 | 9 | .Relacionado 10 | **** 11 | * link:index.html#_pull_requests[Pull Requests] 12 | **** 13 | -------------------------------------------------------------------------------- /src/do/do-fail-fast.adoc: -------------------------------------------------------------------------------- 1 | === Fail fast with faster feedback loops 2 | 3 | Feedback loops include: 4 | 5 | 1. Locally 6 | * Linters 7 | * Automated tests 8 | 2. Continuous Integration (CI) 9 | * Linters 10 | * Automated tests 11 | * Deployment with Continuous Delivery (CD) 12 | 3. Manual / Exploratory testing 13 | 4. ... 14 | 5. All the way to the *Client* and then the *User* 15 | 16 | The sooner feedback and/or change the more efficient it will be. Therefore on the flip side, the later the feedback and/or change the more costly it will be. Not only because it went through more steps to get there, but after the change has been made, it will have to go through all those steps again. 17 | 18 | TIP: Fail fast! 19 | -------------------------------------------------------------------------------- /src/do/do-labels.adoc: -------------------------------------------------------------------------------- 1 | === GitHub Labels 2 | 3 | These are really useful for various reasons: 4 | 5 | - Helps people filter their results, for example by `defect`, `idea` etc 6 | - If people want to contribute to your project a label that states `help needed` will stand out 7 | - Difficulty level. Contributors can filter by a level they are comfortable with. Having some sort of ranking system like beginner, intermediate and expert will help to make it easier for contributors, especially beginners to know which issues to tackle. 8 | 9 | TIP: Have different labels but don't go label crazy, 10-20 is about right 10 | 11 | .Related 12 | **** 13 | * link:index.html#_github_issue_task[Issues & Tasks tips] 14 | **** 15 | -------------------------------------------------------------------------------- /src/do/do-fail-fast-es.adoc: -------------------------------------------------------------------------------- 1 | === Falla rápido con ciclos rápidos de feedback 2 | 3 | Los ciclos de feedback incluyen: 4 | 5 | 1. Localmente 6 | * Linters 7 | * Tests automatizados 8 | 2. Integración Continua (IC) 9 | * Linters 10 | * Tests automatizados 11 | * Deployment con Entrega Continua (EC) 12 | 3. Testeo Manual / Exploratorio 13 | 4. ... 14 | 5. Todo el camino hacia el *Cliente* y luego el *Usuario* 15 | 16 | Mientras más temprano el feedback y/o cambio, más eficiente será. Por lo tanto, la contracara, mientras más tarde el feedback y/o cambio más costoso será. No sólo porque atravesó más etapas para llegar allí, sino porque luego del cambio, deberá volver a pasar por todo el proceso nuevamente. 17 | 18 | TIP: ¡Falla rápido! 19 | -------------------------------------------------------------------------------- /src/do/do-issue-task.adoc: -------------------------------------------------------------------------------- 1 | === GitHub Issue / Task 2 | 3 | Keep these small. Tackling a large piece of work is always daunting and more difficult to find the time. The smaller the tasks, the more likely it is to be done and the lower risk it will be. But remember the task still needs to provide value to the project. 4 | 5 | Include diagrams, screenshots, sub tasks & anything visual to help describe the issue & changes. 6 | 7 | TIP: Don't forget you can use a sub task checklist on https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments[GitHub Issues Checklist]. Sub task list are prepended with `[ ]` for incomplete & `[x]` for complete items. 8 | 9 | .Related 10 | **** 11 | * link:index.html#_github_labels[Labels tips] 12 | **** 13 | -------------------------------------------------------------------------------- /src/do/do-branching-fil.adoc: -------------------------------------------------------------------------------- 1 | === Pagsasanga 2 | 3 | Ang pagsasanga ay mahalaga kung nagtatrabaho sa isang grupo, at mas lalong mahalaga kung nagtatrabaho kasama ang mas malaking grupo na hindi mo pa nakikilala. 4 | 5 | Protektahan ang iyong pangunahing sanga (karaniwang ang `master` o `develop`) at ang lahat ay dapat dumaan sa isang tampok na sangay at isang **Pull Request**. Ito ay dapat na pareho para sa lahat, mga publikong nag-aambag at mga inaprubahang tagapagpanatili. 6 | 7 | TIP: Mayroong maraming stratehiya sa pagsasanga, isang halimbawa ang *Gitflow* - maraming tao ang gumagamit ng bahagi ng http://nvie.com/posts/a-successful-git-branching-model/[Gitflow]. 8 | 9 | .May kaugnayan 10 | **** 11 | * link:index.html#_pull_requests[Pull Requests] 12 | **** 13 | -------------------------------------------------------------------------------- /src/do/do-issue-task-es.adoc: -------------------------------------------------------------------------------- 1 | === GitHub Issue / Tarea 2 | 3 | Mantenlos pequeños. Abordar un trabajo extenso siempre es abrumador y difícil de encontrar un buen momento. Mientras más pequeñas las tareas, más probabilidades tendrán de ser resueltas y el riesgo será menor. Pero recuerda que las tareas deben aportar valor al proyecto. 4 | 5 | Incluye diagramas, capturas de pantalla, sub-tareas y cualquier elemento visual que ayude a describir el issue y los cambios. 6 | 7 | TIP: No olvides que puedes utilizar un checklist para las sub-tareas en https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments[GitHub Issues Checklist]. Las listas de sub-tareas son antepuestas por `[ ]` para items incompletos y `[x]` para items completos. 8 | 9 | .Relacionado 10 | **** 11 | * link:index.html#_github_labels[Consejos para etiquetas] 12 | **** 13 | -------------------------------------------------------------------------------- /src/do/do-accessible.adoc: -------------------------------------------------------------------------------- 1 | === Accessible 2 | 3 | Make the project **Accessible**. 4 | 5 | This has 2 areas: 6 | 7 | 8 | ==== Lower the barrier to entry 9 | 10 | Allow all people, juniors to seniors to be part of the community & contribute. 11 | 12 | * GitHub template <<_github_template_files,more information>> 13 | * Automated tests <<_automation_tests_continuous_integration_ci_continuous_deployment_cd,more information>> 14 | * ... 15 | 16 | ==== The resulting product needs to cater for all 17 | 18 | Access by everyone regardless of disability (e.g. visually impaired) is critical to the success of any project. 19 | 20 | For example: 21 | 22 | * Alternative `alt` text for images 23 | * Keyboard input as well as mouse 24 | * Transcripts for videos 25 | * ...and much more! 26 | * A good place to look for ideas would be https://www.w3.org/WAI/standards-guidelines/ 27 | 28 | TIP: Be inclusive 29 | -------------------------------------------------------------------------------- /src/do/do-accessible-es.adoc: -------------------------------------------------------------------------------- 1 | === Accesible 2 | 3 | Haga que el proyecto sea **Accesible**. 4 | 5 | Esto tiene 2 áreas: 6 | 7 | 8 | ==== Baje la barrera para entrar 9 | 10 | Permita que todas las personas, jóvenes y personas mayores sean parte de la comunidad y contribuyan. 11 | 12 | * Plantilla de GitHub <<_github_template_files,más información>> 13 | * Pruebas automatizadas <<_automation_tests_continuous_integration_ci_continuous_deployment_cd,más información>> 14 | * ... 15 | 16 | ==== El producto resultante necesita atender a todos 17 | 18 | El acceso para cualquier persona independientemente de su discapacidad (por ejemplo, discapacitados visuales) es fundamental para el éxito de cualquier proyecto. 19 | 20 | Por ejemplo: 21 | 22 | * Texto alternativo `alt` para imágenes 23 | * Entrada tanto de teclado como de mouse 24 | * Transcripciones para videos 25 | * ... 26 | 27 | Sugerencia: Sea inclusivo 28 | -------------------------------------------------------------------------------- /.devcontainer/Dockerfile: -------------------------------------------------------------------------------- 1 | # [Choice] Ruby version: 2, 2.7, 2.6, 2.5 2 | ARG VARIANT=2.7 3 | FROM mcr.microsoft.com/vscode/devcontainers/ruby:${VARIANT} 4 | 5 | # [Option] Install Node.js 6 | ARG INSTALL_NODE="true" 7 | ARG NODE_VERSION="lts/*" 8 | RUN if [ "${INSTALL_NODE}" = "true" ]; then su vscode -c "source /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi 9 | 10 | # [Optional] Uncomment this section to install additional OS packages. 11 | # RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \ 12 | # && apt-get -y install --no-install-recommends 13 | 14 | # [Optional] Uncomment this line to install additional gems. 15 | RUN gem install asciidoctor 16 | RUN gem install --pre asciidoctor-pdf 17 | 18 | # [Optional] Uncomment this line to install global node packages. 19 | # RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g " 2>&1 -------------------------------------------------------------------------------- /src/do/do-accessible-fil.adoc: -------------------------------------------------------------------------------- 1 | === Kadalian sa Pagpasok 2 | 3 | Gawing **Mas Madaling Pasukin** ang proyekto. 4 | 5 | Ito ay may dalawang (2) sakop: 6 | 7 | 8 | ==== Ibaba ang hadlang sa pagpasok 9 | 10 | Payagan ang lahat ng mga tao, mapa-baguhan man o higit na nakakaalam na maging parte ng komunidad at mag-ambag. 11 | 12 | * Template ng Github <<_github_template_files,mas maraming impormasyon>> 13 | * Mga pagsusuring isina-awtomatiko <<_automation_tests_continuous_integration_ci_continuous_deployment_cd,mas maraming impormasyon>> 14 | * ... 15 | 16 | ==== Ang resultang produkto ay dapat na magsilbi para sa lahat 17 | 18 | Ang kakayahang makapasok ng lahat, kahit na may kapansanan (hal. may kapansanan sa paningin), ay kritikal sa tagumpay ng anumang proyekto. 19 | 20 | Halimbawa: 21 | 22 | * Alternatibong `alt` teksto para sa mga imahe 23 | * Pag-input gamit ang keyboard at mouse 24 | * Mga salin para sa mga video 25 | * ... 26 | 27 | TIP: Maging mapagpabilang 28 | -------------------------------------------------------------------------------- /src/do/do-code-of-conduct.adoc: -------------------------------------------------------------------------------- 1 | === Code of Conduct 2 | 3 | Your community needs to feel safe, diverse & inclusive. Make sure you have a Code of Conduct for your project & community. Read more about http://contributor-covenant.org[Contributor Covenant - A Code of Conduct for Open Source Projects] 4 | 5 | [quote, Contributor Covenant, Brief overview of the problem] 6 | Open Source has always been a foundation of the Internet, and with the advent of social open source networks this is more true than ever. But free, libre, and open source projects suffer from a startling lack of diversity, with dramatically low participation by women, people of color, and other marginalized populations. 7 | 8 | [quote, Contributor Covenant, Brief overview of the solution] 9 | An easy way to begin addressing this problem is to be overt in our openness, welcoming all people to contribute, and pledging in return to value them as human beings and to foster an atmosphere of kindness, cooperation, and understanding. 10 | -------------------------------------------------------------------------------- /.github/workflows/deploy.yml: -------------------------------------------------------------------------------- 1 | name: Deploy 2 | 3 | on: 4 | push: 5 | branches: [ master ] 6 | workflow_dispatch: 7 | 8 | jobs: 9 | build: 10 | runs-on: ubuntu-latest 11 | 12 | steps: 13 | - uses: actions/checkout@v2 14 | - uses: ruby/setup-ruby@v1 15 | with: 16 | ruby-version: 2.6 17 | 18 | - name: Install asciidoctor 19 | run: | 20 | gem install asciidoctor 21 | gem install --pre asciidoctor-pdf 22 | asciidoctor -v 23 | asciidoctor-pdf -v 24 | 25 | - name: Build 26 | run: | 27 | sed -i -- 's/0.1.0/0.1.'$GITHUB_RUN_NUMBER'/g' src/index.adoc 28 | sed -i -- 's/0.1.0/0.1.'$GITHUB_RUN_NUMBER'/g' src/index-es.adoc 29 | sed -i -- 's/0.1.0/0.1.'$GITHUB_RUN_NUMBER'/g' src/index-fil.adoc 30 | make 31 | 32 | - name: Deploy 33 | uses: JamesIves/github-pages-deploy-action@4.0.0 34 | with: 35 | branch: gh-pages 36 | folder: build 37 | -------------------------------------------------------------------------------- /src/do/do-git-commit.adoc: -------------------------------------------------------------------------------- 1 | === Git commit 2 | 3 | Git commits should be small and atomic, be it a single change or small feature. This will make your commit messages easier to write and and changes will be grouped logically. There are many benefits to this: 4 | 5 | * Looking back through the history will be clear & easy to understand 6 | - if you want to find something 7 | - undo / remove some work 8 | * Automate the changelog generation as part of your build for tag & package etc 9 | 10 | ==== Commit message 11 | 12 | * Limit the subject line to `50` characters 13 | * Do not end the subject line with a period `.`. 14 | * If more than `50` characters use the body (description) 15 | * Wrap the body at `72` characters. 16 | * Use the body to explain `why` not `how`, this can been seen in the code 17 | 18 | More information http://chris.beams.io/posts/git-commit/[Git Commit] 19 | 20 | TIP: Before doing the commit, check the `git diff` to make sure you are not committing anything you do not want to, or should not be. 21 | -------------------------------------------------------------------------------- /src/do/do-contribution-file.adoc: -------------------------------------------------------------------------------- 1 | === Contribution file 2 | 3 | One of the main benefits of an Open Source project & its community contributions. Lower the barrier to entry with a `CONTRIBUTING.md` file in the root of your Open Source project. Read more about https://github.com/blog/1184-contributing-guidelines[GitHub Contribution file] 4 | 5 | [quote, GitHub, GitHub Contributing Guidelines] 6 | Often times open source projects place a CONTRIBUTING file in the root directory. It explains how a participant should do things like format code, test fixes, and submit patches. Here is a fine example from puppet and another one from factory_girl_rails. From a maintainer's point of view, the document succinctly communicates how best to collaborate. And for a contributor, one quick check of this file verifies their submission follows the maintainer's guidelines. 7 | 8 | image::github-contributing-file.png[caption="", role="thumb", title="GitHub Contributing Guidelines", alt="GitHub Contributing Guidelines", link="https://github.com/blog/1184-contributing-guidelines"] 9 | -------------------------------------------------------------------------------- /src/do/do-automation.adoc: -------------------------------------------------------------------------------- 1 | === Automation - Tests, Continuous Integration (CI), Continuous Deployment (CD) 2 | 3 | *Automate everything*! This helps lower the barrier to entry & increase repeatability. 4 | 5 | * Automated tests have many benefits & give confidence in the state & quality of the application: 6 | - Unit tests are great for design & architecture of functionality 7 | - Integration tests are great for the touch points 8 | - End-to-end tests are great for full application testing & simulate the user 9 | * It should be very easy to setup up a local environment & run all these tests 10 | * Run the automated tests on Continuous Integration (CI) after someone has pushed their code changes to a feature branch 11 | * When automated tests are successful, deploy the application aka Continuous Delivery (CD) 12 | 13 | NOTE: This includes database schema migrations, asset building and anything that is required by the end product 14 | 15 | TIP: http://travis-ci.org[TravisCI] is highly recommended in Open Source projects. Very easy to set up & get going, all from a simple YAML file. 16 | -------------------------------------------------------------------------------- /src/do/do-git-commit-es.adoc: -------------------------------------------------------------------------------- 1 | === Git commit 2 | 3 | Los commits en Git deben ser pequeños y atómicos, ya sea un pequeño cambio o característica. Esto hará tus mensajes de commit más fáciles de escribir y los cambios se agruparán localmente. Hay varios beneficios a esto: 4 | 5 | * Revisar el historial será claro y fácil de entender 6 | - si quieres encontrar algo 7 | - deshacer / remover algún trabajo 8 | * Automatizar la generación del registro de cambios como parte de tu versión para etiquetar y empaquetar, etc 9 | 10 | ==== Mensaje de commit 11 | 12 | * Limita el mensaje de asunto a `50` caracteres 13 | * No finalices el mensaje con un punto `.`. 14 | * Si precisas más de `50` caracteres utiliza el cuerpo (descripción) 15 | * Limita el cuerpo a `72` caracteres 16 | * Utiliza el cuerpo para explicar `porqué` no `cómo`, esto puede verse en tu código 17 | 18 | Más información en http://chris.beams.io/posts/git-commit/[Git Commit] 19 | 20 | TIP: Antes de realizar el commit, chequea el `git diff` para asegurarte que no estás commiteando algo que no quieres, o que no debería serlo. 21 | -------------------------------------------------------------------------------- /.devcontainer/devcontainer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "Ruby", 3 | "build": { 4 | "dockerfile": "Dockerfile", 5 | "args": { 6 | // Update 'VARIANT' to pick a Ruby version: 2, 2.7, 2.6, 2.5 7 | "VARIANT": "2", 8 | // Options 9 | "INSTALL_NODE": "true", 10 | "NODE_VERSION": "lts/*" 11 | } 12 | }, 13 | 14 | // Set *default* container specific settings.json values on container create. 15 | "settings": { 16 | "terminal.integrated.shell.linux": "/bin/bash" 17 | }, 18 | 19 | // Add the IDs of extensions you want installed when the container is created. 20 | "extensions": [ 21 | "rebornix.Ruby", 22 | "joaompinto.asciidoctor-vscode", 23 | "ritwickdey.liveserver" 24 | ], 25 | 26 | // Use 'forwardPorts' to make a list of ports inside the container available locally. 27 | "forwardPorts": [5500], 28 | 29 | // Use 'postCreateCommand' to run commands after the container is created. 30 | // "postCreateCommand": "ruby --version", 31 | 32 | // Uncomment to connect as a non-root user. See https://aka.ms/vscode-remote/containers/non-root. 33 | // "remoteUser": "vscode" 34 | 35 | } -------------------------------------------------------------------------------- /src/do/do-code-of-conduct-es.adoc: -------------------------------------------------------------------------------- 1 | === Código de Conducta 2 | 3 | Su comunidad necesita sentirse segura, diversa e inclusiva. Asegúrese de tener un Código de Conducta para su proyecto y comunidad. Lea más acerca de http://contributor-covenant.org[Convenio de Colaboradores: Un Código de Conducta para Proyectos de Código Abierto] 4 | 5 | [quote, Convenio de Colaboradores, Breve reseña del problema] 6 | El código abierto siempre ha sido la base de Internet, y con la llegada de las redes sociales de código abierto, esto es más cierto que nunca. Pero los proyectos gratuitos, libres y de código abierto sufren de una sorprendente falta de diversidad, con una participación dramáticamente baja de mujeres, personas de color y otras poblaciones marginadas. 7 | 8 | [quote, Convenio de Colaboradores, Breve reseña de la solución] 9 | Una forma fácil de comenzar a abordar este problema es ser abiertos en nuestra receptividad, dándole la bienvenida a todas las personas para que contribuyan y comprometiéndonos a cambio de valorarlas como seres humanos y fomentar una atmósfera de bondad, cooperación y comprensión. 10 | -------------------------------------------------------------------------------- /src/do.adoc: -------------------------------------------------------------------------------- 1 | include::do/do-readme.adoc[] 2 | 3 | include::do/do-code-block.adoc[] 4 | 5 | include::do/do-contribution-file.adoc[] 6 | 7 | include::do/do-explore-open-source-projects.adoc[] 8 | 9 | include::do/do-code-of-conduct.adoc[] 10 | 11 | include::do/do-github-template-files.adoc[] 12 | 13 | include::do/do-licensing.adoc[] 14 | 15 | include::do/do-git-commit.adoc[] 16 | 17 | include::do/do-little-and-often.adoc[] 18 | 19 | include::do/do-plan-ahead.adoc[] 20 | 21 | include::do/do-issue-task.adoc[] 22 | 23 | include::do/do-always-respond.adoc[] 24 | 25 | include::do/do-pull-request.adoc[] 26 | 27 | include::do/do-review.adoc[] 28 | 29 | include::do/do-automation.adoc[] 30 | 31 | include::do/do-prototyping.adoc[] 32 | 33 | include::do/do-optimal-time.adoc[] 34 | 35 | include::do/do-not-enough-time.adoc[] 36 | 37 | include::do/do-codebase-improvements.adoc[] 38 | 39 | include::do/do-fail-fast.adoc[] 40 | 41 | include::do/do-accessible.adoc[] 42 | 43 | include::do/do-labels.adoc[] 44 | 45 | include::do/do-milestone.adoc[] 46 | 47 | include::do/do-release.adoc[] 48 | 49 | include::do/do-branching.adoc[] 50 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2016 Eddie Jaoude 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /src/do/do-contribution-file-es.adoc: -------------------------------------------------------------------------------- 1 | === Archivo de contribución 2 | 3 | Uno de los principales beneficios de un proyecto de Código Abierto y sus contribuciones a la comunidad. Baje la barrera para entrar con un archivo `CONTRIBUTING.md` en la raíz de su proyecto de Código Abierto. Obtenga más información sobre https://github.com/blog/1184-contributing-guidelines[Archivo de contribución de GitHub] 4 | 5 | [quote, GitHub, Pautas de Contribución de GitHub] 6 | Muchas veces los proyectos de código abierto colocan un archivo CONTRIBUYENTE en el directorio raíz. Explica cómo un participante debe hacer las cosas, como código de formato, correcciones de prueba y enviar parches. Aquí hay un buen ejemplo de puppet y otro de factory_girl_rails. Desde el punto de vista de un mantenedor, el documento comunica de manera sucinta la mejor manera de colaborar. Y para un colaborador, una revisión rápida de este archivo verifica que su presentación sigue las pautas del mantenedor. 7 | 8 | image::github-contributing-file.png[caption="", role="thumb", title="Pautas de Contribución de GitHub", alt="Pautas de Contribución de GitHub", link="https://github.com/blog/1184-contributing-guidelines"] 9 | -------------------------------------------------------------------------------- /src/do-fil.adoc: -------------------------------------------------------------------------------- 1 | include::do/do-readme.adoc[] 2 | 3 | include::do/do-code-block-fil.adoc[] 4 | 5 | include::do/do-contribution-file-fil.adoc[] 6 | 7 | include::do/do-explore-open-source-projects-fil.adoc[] 8 | 9 | include::do/do-code-of-conduct-fil.adoc[] 10 | 11 | include::do/do-github-template-files.adoc[] 12 | 13 | include::do/do-licensing.adoc[] 14 | 15 | include::do/do-git-commit.adoc[] 16 | 17 | include::do/do-little-and-often.adoc[] 18 | 19 | include::do/do-plan-ahead.adoc[] 20 | 21 | include::do/do-issue-task.adoc[] 22 | 23 | include::do/do-always-respond-fil.adoc[] 24 | 25 | include::do/do-pull-request.adoc[] 26 | 27 | include::do/do-review.adoc[] 28 | 29 | include::do/do-automation-fil.adoc[] 30 | 31 | include::do/do-prototyping.adoc[] 32 | 33 | include::do/do-optimal-time.adoc[] 34 | 35 | include::do/do-not-enough-time.adoc[] 36 | 37 | include::do/do-codebase-improvements-fil.adoc[] 38 | 39 | include::do/do-fail-fast.adoc[] 40 | 41 | include::do/do-accessible-fil.adoc[] 42 | 43 | include::do/do-labels.adoc[] 44 | 45 | include::do/do-milestone.adoc[] 46 | 47 | include::do/do-release.adoc[] 48 | 49 | include::do/do-branching-fil.adoc[] 50 | -------------------------------------------------------------------------------- /src/do/do-explore-open-source-projects.adoc: -------------------------------------------------------------------------------- 1 | === Explore open source projects 2 | 3 | Remember to explore other open source projects out there to see how other projects have been successfully managed, and what their outcomes looked like. 4 | 5 | Here are 10 examples of open source projects to start you off: 6 | 7 | - https://24pullrequests.com/projects[24 Pull Requests] 8 | - https://github.com/dwyl[dwyl - do what you love] 9 | - https://github.com/foundersandcoders[Founders & Coders] 10 | - https://github.com/HackBrexit[Hack Brexit] 11 | - https://github.com/WeRockTech[We Rock Tech] 12 | - https://github.com/womenhackfornonprofits[Women Who Hack For Non Profits] 13 | - https://github.com/elixirkoans/elixir-koans[Elixir Koans] 14 | - https://github.com/codebar[Codebar] 15 | - https://github.com/rails-girls-summer-of-code[Rails Girls Summer of Code] 16 | - https://github.com/voteamerica/voteamerica.github.io[Vote America] 17 | 18 | TIP: The more open source projects you have explored, the more you'll see what practices have worked and what have not. This will equip you with more knowledge on how you'd like to run your project in practice, based on existing projects you've come across. 19 | -------------------------------------------------------------------------------- /src/do-es.adoc: -------------------------------------------------------------------------------- 1 | include::do/do-readme-es.adoc[] 2 | 3 | include::do/do-code-block-es.adoc[] 4 | 5 | include::do/do-contribution-file-es.adoc[] 6 | 7 | include::do/do-explore-open-source-projects-es.adoc[] 8 | 9 | include::do/do-code-of-conduct-es.adoc[] 10 | 11 | include::do/do-github-template-files-es.adoc[] 12 | 13 | include::do/do-licensing-es.adoc[] 14 | 15 | include::do/do-git-commit-es.adoc[] 16 | 17 | include::do/do-little-and-often.adoc[] 18 | 19 | include::do/do-plan-ahead-es.adoc[] 20 | 21 | include::do/do-issue-task-es.adoc[] 22 | 23 | include::do/do-always-respond-es.adoc[] 24 | 25 | include::do/do-pull-request-es.adoc[] 26 | 27 | include::do/do-review-es.adoc[] 28 | 29 | include::do/do-automation-es.adoc[] 30 | 31 | include::do/do-prototyping-es.adoc[] 32 | 33 | include::do/do-optimal-time-es.adoc[] 34 | 35 | include::do/do-not-enough-time-es.adoc[] 36 | 37 | include::do/do-codebase-improvements-es.adoc[] 38 | 39 | include::do/do-fail-fast-es.adoc[] 40 | 41 | include::do/do-accessible-es.adoc[] 42 | 43 | include::do/do-labels-es.adoc[] 44 | 45 | include::do/do-milestone-es.adoc[] 46 | 47 | include::do/do-release-es.adoc[] 48 | 49 | include::do/do-branching-es.adoc[] 50 | -------------------------------------------------------------------------------- /src/do/do-github-template-files.adoc: -------------------------------------------------------------------------------- 1 | === GitHub template files 2 | 3 | Issue & Pull Request templates really help keeping the project consistent & reminds people not to leave out certain useful information. 4 | 5 | [quote, GitHub, GitHub Issue Template] 6 | To add an Issue template to a repository create a file called ISSUE_TEMPLATE in the root directory. A file extension is optional, but Markdown files (.md) are supported. Markdown support makes it easy to add things like headings, links, @-mentions, and task lists to your templates. 7 | 8 | [quote, GitHub, GitHub Pull Request Template] 9 | Pull Request templates follows the same pattern: add a file called PULL_REQUEST_TEMPLATE to the root directory of your repository. 10 | 11 | [quote, GitHub, GitHub Hidden Directory for Templates] 12 | If you're worried about the added clutter in the root directory of your project, we also added support for a .github/ folder. You can put CONTRIBUTING.md, ISSUE_TEMPLATE.md, and PULL_REQUEST_TEMPLATE.md files in .github/ and everything will work as expected. 13 | 14 | https://help.github.com/articles/helping-people-contribute-to-your-project/[Full details from GitHub] for helping people contribute to your project 15 | -------------------------------------------------------------------------------- /src/do/do-code-of-conduct-fil.adoc: -------------------------------------------------------------------------------- 1 | === Alituntunin sa Pagkilos 2 | 3 | Ang iyong komunidad ay kailangang makaranas ng pagiging ligtas, pagkakaiba, at pagkakabilang. Siguraduhin mong mayroon kang Alituntunin sa Pagkilos para sa iyong proyekto at komunidad. Magbasa pa tungkol sa http://contributor-covenant.org[Tipan ng Taga-ambag - Isang Alituntunin sa Pagkilos para sa mga proyektong Open Source] 4 | 5 | [quote, Tipan ng Taga-ambag, Maikling kabuuran ng problema] 6 | Ang Open Source ay lagi ng maituturing na pundasyon ng Internet, at sa pagdating ng mga panlipunang open source na network, ito ay mas naging tunay higit pa kaysa dati. Ngunit ang malaya, libre, at mga proyektong open source ay nagdurusa sa kakulangan sa pagkakaiba-iba - sa kapansin-pansin na mababang partisipasyon ng mga kababaihan, mga taong may kulay, at iba pang mga naka-marhinalisang populasyon. 7 | 8 | [quote, Tipan ng Taga-ambag, Maikling kabuuran ng solusyon] 9 | Isang madaling paraan para masimulang pagtuunan ng pansin ang problemang ito ay ang hayagang pagiging bukas natin, pagsalubong sa lahat ng mga nag-aambag, at ang pangakong pahalagahan sila bilang mga tao at pagpapaunlad sa kapaligiran ng kabutihan, kooperasyon, at pag-iintindi. 10 | -------------------------------------------------------------------------------- /src/do/do-explore-open-source-projects-es.adoc: -------------------------------------------------------------------------------- 1 | === Explora proyectos de código abierto 2 | 3 | Recuerde explorar otros proyectos de código abierto para ver cómo otros proyectos se han administrado con éxito y cuáles fueron sus resultados. 4 | 5 | Aquí hay 10 ejemplos de proyectos de código abierto para comenzar: 6 | 7 | - https://24pullrequests.com/projects[24 Pull Requests] 8 | - https://github.com/dwyl[dwyl - do what you love] 9 | - https://github.com/foundersandcoders[Founders & Coders] 10 | - https://github.com/HackBrexit[Hack Brexit] 11 | - https://github.com/WeRockTech[We Rock Tech] 12 | - https://github.com/womenhackfornonprofits[Women Who Hack For Non Profits] 13 | - https://github.com/elixirkoans/elixir-koans[Elixir Koans] 14 | - https://github.com/codebar[Codebar] 15 | - https://github.com/rails-girls-summer-of-code[Rails Girls Summer of Code] 16 | - https://github.com/voteamerica/voteamerica.github.io[Vote America] 17 | 18 | CONSEJO: Cuantos más proyectos de código abierto haya explorado, más verá qué prácticas han funcionado y cuáles no. Esto le proporcionará más conocimiento sobre cómo le gustaría ejecutar su proyecto en la práctica, en función de los proyectos existentes que haya conocido. 19 | -------------------------------------------------------------------------------- /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | We love pull requests from everyone. By participating in this project, you 4 | agree to abide by the [Contributor Covenant](http://contributor-covenant.org). 5 | 6 | ## Steps 7 | 8 | 1. [Fork](https://help.github.com/articles/fork-a-repo/) this [project](https://github.com/eddiejaoude/book-open-source-tips) 9 | 2. [Clone](https://docs.github.com/get-started/quickstart/fork-a-repo#cloning-your-forked-repository) your forked version `git clone git@github.com:/book-open-source-tips.git` 10 | 3. Make changes (mostly probably in `src/` directory) 11 | 4. [Commit](https://help.github.com/articles/adding-a-file-to-a-repository-using-the-command-line/) your changes (write a short descriptive message of what you have done) 12 | 5. [Push](https://help.github.com/articles/pushing-to-a-remote/) your changes to your forked version 13 | 6. Go to original project on GitHub & Create a [Pull Request](https://help.github.com/articles/about-pull-requests/) 14 | 15 | **DONE** 16 | 17 | Once the **Pull Request** has been accepted & merged into `master`, it will automatically be built (with [AsciiDoctor](http://asciidoctor.org) html & pdf) & [deployed](https://eddiejaoude.github.io/book-open-source-tips/) 18 | -------------------------------------------------------------------------------- /src/do/do-explore-open-source-projects-fil.adoc: -------------------------------------------------------------------------------- 1 | === Magsaliksik ng mga proyektong Open Source 2 | 3 | Alalahaning magsaliksik ng iba pang mga proyektong open source para makita kung paanong matagumpay na napapamahalaan ang ibang mga proyekto, at kung ano ang kinalalabasan nila. 4 | 5 | Narito ang 10 halimbawa ng mga proyektong open source para makapagsimula ka: 6 | 7 | - https://24pullrequests.com/projects[24 Pull Requests] 8 | - https://github.com/dwyl[dwyl - do what you love] 9 | - https://github.com/foundersandcoders[Founders & Coders] 10 | - https://github.com/HackBrexit[Hack Brexit] 11 | - https://github.com/WeRockTech[We Rock Tech] 12 | - https://github.com/womenhackfornonprofits[Women Who Hack For Non Profits] 13 | - https://github.com/elixirkoans/elixir-koans[Elixir Koans] 14 | - https://github.com/codebar[Codebar] 15 | - https://github.com/rails-girls-summer-of-code[Rails Girls Summer of Code] 16 | - https://github.com/voteamerica/voteamerica.github.io[Vote America] 17 | 18 | TIP: Kung mas marami kang mga proyektong open source na masasaliksik, mas makikita mo kung aling mga pagsasanay ang gumana at kung alin ang hindi. Mabibigyan ka nito ng mas maraming kaalaman sa kung paano mo gugustuhing patakbuhin ang iyong proyekto, base sa mga umiiral na proyektong iyong nakatagpo. 19 | -------------------------------------------------------------------------------- /src/do/do-automation-es.adoc: -------------------------------------------------------------------------------- 1 | === Automatización - Pruebas, Integración continua (IC), Despliegue Continuo (DC) 2 | 3 | ¡*Automatice todo*! Esto ayuda a reducir la barrera para entrar y aumentar la repetibilidad. 4 | 5 | * Las pruebas automatizadas tienen muchos beneficios y dan confianza en el estado y la calidad de la aplicación: 6 | - Las pruebas unitarias son excelentes para el diseño y la arquitectura de la funcionalidad 7 | - Las pruebas de integración son geniales para los puntos de contacto 8 | - Las pruebas de extremo a extremo son excelentes para realizar pruebas completas de aplicaciones y simular al usuario 9 | * Debería ser muy fácil configurar un entorno local y ejecutar todas estas pruebas 10 | * Ejecute las pruebas automatizadas en Integración continua (IC) después de que alguien haya introducido sus cambios de código en una rama específica 11 | * Cuando las pruebas automáticas son exitosas, implemente la aplicación conocida como Entrega Continua (ED) 12 | 13 | NOTA: Esto incluye migraciones de esquema de bases de datos, creación de activos estáticos y cualquier cosa que requiera el producto final 14 | 15 | CONSEJO: http://travis-ci.org[TravisCI] es muy recomendable en proyectos de código abierto. Muy fácil de instalar y poner en marcha, todo desde un simple archivo `yamla. 16 | -------------------------------------------------------------------------------- /src/do/do-contribution-file-fil.adoc: -------------------------------------------------------------------------------- 1 | === Talaksan ng Ambag 2 | 3 | Isa sa mga pangunahing benepisyo ng isang proyektong Open Source at ng mga ambag nito sa komunidad. Pababain ang hadlang sa pagpasok gamit ang `CONTRIBUTING.md` na file sa ugat ng iyong proyektong Open Source. Magbasa pa tungkol sa https://github.com/blog/1184-contributing-guidelines[Talaksan ng ambag sa GitHub] 4 | 5 | [quote, GitHub, Mga Patnubay sa Pag-ambag sa Github] 6 | Kadalasan, ang mga proyektong open source ay naglalagay ng isang NAG-AAMBAG na file sa ugat na direktoryo. Ipinapaliwanag nito kung paano gawin ng isang kasapi ang mga bagay tulad ng pag-format ng code, pagsusuri sa mga inayos, at pagsusumite ng mga patse. Narito ang isang magandang halimbawa galing sa papet at isa mula sa factory_girl_rails. Mula sa pananaw ng tagapagpatuloy, maikli ngunit malinaw na pinapahayag ng dokumento kung paano pinakamabuting makipagtulungan. At para sa isang nag-aambag, isang mabilisang pagsusuri ng mga talaksang ito ay magpapatunay na ang mga isinumite nila ay sumusunod sa mga patnubay ng tagapagpatuloy. 7 | 8 | image::github-contributing-file.png[caption="Mga Patnubay sa Pag-ambag sa Github", role="thumb", title="Mga Patnubay sa Pag-ambag sa Github", alt="Mga Patnubay sa Pag-ambag sa Github", link="https://github.com/blog/1184-contributing-guidelines"] 9 | -------------------------------------------------------------------------------- /src/do/do-pull-request.adoc: -------------------------------------------------------------------------------- 1 | === Pull Requests 2 | 3 | If you spent the time doing the work, make sure you add a description to your your Pull Request to make it easier for the reviewer to digest your work. Raise an Issue first so a plan of action can be discussed before you begin the work and to remind yourself of the goals set out in that task. 4 | 5 | Pull Requests should be linked to the original Issue it is trying to solve. This can be done with using `#` followed by the *Issue No*, e.g. `#123`. The Issue description will contain the information before, therefore the Pull Request description should contain the information after the changes. Include visual material too, for example diagrams & screenshots. 6 | 7 | Remember, keep it small. For example if your changes contains a feature or bug fix & code styling changes, these should be in separate Pull Requests. Every project would rather have 10 Pull Requests, than 1 or 2 massive Pull Requests. 8 | 9 | TIP: Pull Request should be a single feature or change. 10 | 11 | Multiple commits in a Pull Request highlight the creation steps of the Pull Request. Do not try to do everything in a single commit. 12 | 13 | Comments do matter, if in doubt, put it in, they can more easily be removed than added. Don't describe how, that is obviously in the code, describe why. 14 | -------------------------------------------------------------------------------- /src/do/do-github-template-files-es.adoc: -------------------------------------------------------------------------------- 1 | === Plantillas de Github 2 | 3 | Las plantillas de Issue y Pull Request realmente ayudan a mantener el proyecyo consistente y recuerdan a las personas no dejar afuera cierta información útil. 4 | 5 | [quote, GitHub, Plantilla para Issue de GitHub] 6 | Para agregar una plantilla de Issue a un repositorio cree un archivo llamado ISSUE_TEMPLATE en el directorio raíz. Una extensión de archivo es opcional, pero los archivos Markdown (.md) son soportados. El soporte para Markdown hace más fácil agregar cosas como títulos, enlaces, @-menciones, y listas de tareas a tus plantillas. 7 | 8 | [quote, GitHub, Plantilla para Pull Request de GitHub] 9 | Las plantillas para Pull Request siguen el mismo patrón: agrega un archivo denominado PULL_REQUEST_TEMPLATE al directorio raíz de tu repositorio. 10 | 11 | [quote, GitHub, Directorio Oculto de GitHub para Plantillas] 12 | Si te preocupa la desorganización creada en el directorio raíz de tu proyecto, también hemos agregado soporte para una carpeta .github/. Puedes poner los archivos CONTRIBUTING.md, ISSUE_TEMPLATE.md, y PULL_REQUEST_TEMPLATE.md en .github/ y todo seguirá funciona como estaba previsto. 13 | 14 | https://help.github.com/articles/helping-people-contribute-to-your-project/[Detalles completos de GitHub] para ayudar a las personas a contribuir en tu proyecto 15 | -------------------------------------------------------------------------------- /src/do/do-readme.adoc: -------------------------------------------------------------------------------- 1 | === Readme file 2 | 3 | Documentation is usually left to last. Start every project with at least a `README.md` with basic information, for example a description & quickstart guide, if you change features or functionality, try at least to update this with your commits. 4 | 5 | Example README.md 6 | 7 | ``` 8 | # Name of Project 9 | 10 | Include any project badges (e.g. CI) here at the top. 11 | 12 | Description of project & its goals. 13 | 14 | Also include what it does not do. 15 | 16 | 17 | ## Screenshots 18 | 19 | Nothing says more than screenshots. 20 | 21 | 22 | ## Dependencies 23 | 24 | Any dependencies required by the project. 25 | 26 | 27 | ## Installation 28 | 29 | How to install on Mac... 30 | 31 | How to install on Linux... 32 | 33 | How to install on Windows... 34 | 35 | 36 | ## Usage 37 | 38 | How to use the project 39 | 40 | 41 | ## Contribution SetUp 42 | 43 | If people would like to contribute, what steps should they take. 44 | 45 | Overview here and a link to the `CONTRIBUTION.md` file with more details 46 | 47 | 48 | ## Code of Conduct 49 | 50 | Overview of Code of Conduct, with link to `CODE_OF_CONDUCT.MD` 51 | 52 | 53 | ## Change log / Release history 54 | 55 | Major version & breaking changes 56 | 57 | 58 | ## Meta data 59 | 60 | Any other useful information. 61 | 62 | ``` 63 | -------------------------------------------------------------------------------- /src/do/do-automation-fil.adoc: -------------------------------------------------------------------------------- 1 | === Pagsasa-awtomatiko - Mga Pagsusuri, Patuloy na Integrasyon (PI), Patuloy na Pagtatalaga (PP) 2 | 3 | *Isa-awtomatiko lahat*! Ito'y tumutulong para mapababa ang hadlang sa pagpasok at pataasin ang pagkakaulit. 4 | 5 | * Ang mga pagsusuring isina-awtomatiko ay maraming taglay na kabutihan at nagbibigay kumpiyansa sa estado at kalidad ng aplikasyon: 6 | - Ang mga yunit na pagsusuri ay mabuti para sa disenyo at arkitektura ng pagpapaandar 7 | - Ang mga pagsusuri sa integrasyon ay mabuti para sa mga puntong mahahawakan 8 | - Ang mga punto por puntong pagsusuri ay mabuti para sa ganap na pagsusuri sa aplikasyon at pagkunuwa sa gumagamit 9 | * Ang pag-setup ng lokal na kapaligiran at pagpapairal sa lahat ng mga pagsusuring ito ay madali lamang 10 | * Pairalin ang mga isina-awtomatikong pagsusuri sa Patuloy na Integrasyon (PI) matapos maitulak ng isang tao ang mga pagbabago sa kowd sa isang tampok na sangay 11 | * Kung ang mga isina-awtomatikong pagsusuri ay matagumpay, italaga ang aplikasyon o mas kilala bilang Patuloy na Pagtatalaga (PP) 12 | 13 | PAALALA: Ito ay sumasaklaw sa mga paglipat ng database schema, pagtatayo ng asset, at anuman na kinakailangan ng resultang produkto 14 | 15 | TIP: Ang http://travis-ci.org[TravisCI] ay lubos na nirerekomenda sa mga proyektong Open Source. Napakadaling i-setup at gamitin, lahat mula sa simpleng `yamla file. 16 | -------------------------------------------------------------------------------- /src/do/do-readme-es.adoc: -------------------------------------------------------------------------------- 1 | === Archivo Readme 2 | 3 | La documentación es algo que suele dejarse para el final. Comienza cada proyecto con, al menos, un archivo `README.md` con información básica, por ejemplo, una descripción y guía de inicio rápido, si cambias alguna característica o funcionalidad, intenta al menos actualizarlo en conjunto con tus commits. 4 | 5 | Ejemplo README.md 6 | 7 | ``` 8 | # Nombre del Proyecto 9 | 10 | Incluye cualquier identificación del proyecto (ej. CI) aquí al comienzo. 11 | 12 | Descripción del proyecto y sus objetivos. 13 | 14 | Incluye también lo que no hace. 15 | 16 | 17 | ## Capturas de pantalla 18 | 19 | Nada dice más que las capturas de pantalla. 20 | 21 | 22 | ## Dependencias 23 | 24 | Cualquier dependencia requerida por el proyecto. 25 | 26 | 27 | ## Instalación 28 | 29 | Cómo instalar en Mac... 30 | 31 | Cómo instalar en Linux... 32 | 33 | Cómo instalar en Windows... 34 | 35 | 36 | ## Uso 37 | 38 | Cómo utilizar el proyecto 39 | 40 | 41 | ## Configuración de Contribuciones 42 | 43 | Si la gente quiere contribuir, qué pasos deberían seguir. 44 | 45 | Resumen y enlace al archivo `CONTRIBUTION.md` con más detalles. 46 | 47 | 48 | ## Código de Conducta 49 | 50 | Resumen del Código de Conducta, con un enlace a `CODE_OF_CONDUCT.md`. 51 | 52 | 53 | ## Registro de Cambios / Historial de Versiones 54 | 55 | Versión principal y cambios importantes. 56 | 57 | 58 | ## Meta data 59 | 60 | Cualquier otra información útil. 61 | 62 | ``` 63 | -------------------------------------------------------------------------------- /src/do/do-pull-request-es.adoc: -------------------------------------------------------------------------------- 1 | === Pull Requests 2 | 3 | Si te has tomado el tiempo de realizar el trabajo, asegúrate de agregar una descripción a tu Pull Request para facilitar la tarea de procesar lo que has hecho a quien lo revise. Crea un Issue primero para que un plan de trabajo pueda ser discutido antes de que comiences el trabajo y para recordarte a ti mismo las metas propuestas en la tarea. 4 | 5 | Los Pull Requests deberían estar enlazados al Issue original que intentan resolver. Esto puede realizarse utilizando un `#` seguido de *Issue No*, por ejemplo: `#123`. La descripción del Issue contendrá la información previa a los cambios, por consiguiente, la descripción del Pull Request deberá contener la información posterior a los mismos. Incluye material visual también, por ejemplo, diagramas y capturas de pantalla. 6 | 7 | Recuerda, mantenlo conciso. Por ejemplo, si tus cambios contienen una característica o arreglo de un bug y cambios de estilo, éstos deberían estar en Pull Requests separados. Es mejor que cada proyecto tenga 10 Pull Requests, que 1 o 2 Pull Requests masivos. 8 | 9 | TIP: Los Pull Request deberían ser una característica o cambio individual. 10 | 11 | Múltiples commits en un Pull Request resaltan la creación de pasos en el Pull Request. No intentes hacer todo en un solo commit. 12 | 13 | Los comentarios importan, si estás en duda, agrégalo, pueden ser removidos con más facilidad que agregados. No describas el cómo, eso obviamente se encuentra en el código, describe el porqué. 14 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | all: reset assets html pdf 2 | 3 | reset: 4 | rm -fr build/* 5 | 6 | assets: 7 | cp -r src/images/ build/images/ 8 | cp -r src/favicon.ico build/ 9 | 10 | html: 11 | asciidoctor src/index.adoc -D build/ 12 | asciidoctor src/index-es.adoc -D build/ 13 | asciidoctor src/index-fil.adoc -D build/ 14 | 15 | pdf: 16 | asciidoctor -r asciidoctor-pdf -b pdf -a pdf-style=config/pdf-theme.yml src/index.adoc -D build/ 17 | mv build/index.pdf build/open-source-tips.pdf 18 | 19 | pipeline.version.startBuild: 20 | curl -XPOST -H "Content-Type: application/json" -d '{"release":"v0.1.${TRAVIS_BUILD_NUMBER}"}' https://api-pipeline.dashboardhub.io/environments/f39a2d40-2045-11e8-a435-ade829eb4121/deployed/${DH_TOKEN}/startBuild 21 | 22 | pipeline.version.finishBuild: 23 | curl -XPOST -H "Content-Type: application/json" -d '{"release":"v0.1.${TRAVIS_BUILD_NUMBER}"}' https://api-pipeline.dashboardhub.io/environments/f39a2d40-2045-11e8-a435-ade829eb4121/deployed/${DH_TOKEN}/finishBuild 24 | 25 | pipeline.version.failBuild: 26 | curl -XPOST -H "Content-Type: application/json" -d '{"release":"v0.1.${TRAVIS_BUILD_NUMBER}"}' https://api-pipeline.dashboardhub.io/environments/f39a2d40-2045-11e8-a435-ade829eb4121/deployed/${DH_TOKEN}/failBuild 27 | 28 | pipeline.version.startDeploy: 29 | curl -XPOST -H "Content-Type: application/json" -d '{"release":"v0.1.${TRAVIS_BUILD_NUMBER}"}' https://api-pipeline.dashboardhub.io/environments/f39a2d40-2045-11e8-a435-ade829eb4121/deployed/${DH_TOKEN}/startDeploy 30 | 31 | pipeline.version.finishDeploy: 32 | curl -XPOST -H "Content-Type: application/json" -d '{"release":"v0.1.${TRAVIS_BUILD_NUMBER}"}' https://api-pipeline.dashboardhub.io/environments/f39a2d40-2045-11e8-a435-ade829eb4121/deployed/${DH_TOKEN}/finishDeploy 33 | 34 | pipeline.version.failDeploy: 35 | curl -XPOST -H "Content-Type: application/json" -d '{"release":"v0.1.${TRAVIS_BUILD_NUMBER}"}' https://api-pipeline.dashboardhub.io/environments/f39a2d40-2045-11e8-a435-ade829eb4121/deployed/${DH_TOKEN}/failDeploy 36 | -------------------------------------------------------------------------------- /src/do/do-licensing.adoc: -------------------------------------------------------------------------------- 1 | === Licensing 2 | 3 | It is not required to select a license, however by doing so, you are selecting "No License" which will default you to the https://help.github.com/articles/github-terms-of-service/[T&Cs] of GitHub. GitHub have created a great informational website to help you choose a http://choosealicense.com[license] 4 | 5 | Examples below from http://choosealicense.com["Choose an open source license"]: 6 | 7 | [quote, Choose a License, MIT License] 8 | The MIT License is a permissive license that is short and to the point. It lets people do anything they want with your code as long as they provide attribution back to you and don’t hold you liable. 9 | 10 | NOTE: jQuery, .NET Core, and Rails use the MIT License. 11 | 12 | [quote, Choose a License, Apache License 2.0] 13 | The Apache License 2.0 is a permissive license similar to the MIT License, but also provides an express grant of patent rights from contributors to users. 14 | 15 | NOTE: Android, Apache, and Swift use the Apache License 2.0. 16 | 17 | [quote, Choose a License, GNU GPLv3] 18 | The GNU GPLv3 is a copyleft license that requires anyone who distributes your code or a derivative work to make the source available under the same terms, and also provides an express grant of patent rights from contributors to users. 19 | 20 | NOTE: Bash, GIMP, and Privacy Badger use the GNU GPLv3. 21 | 22 | [quote, Choose a License, No License] 23 | When you make a creative work (which includes code), the work is under exclusive copyright by default. Unless you include a license that specifies otherwise, nobody else can use, copy, distribute, or modify your work without being at risk of take-downs, shake-downs, or litigation. Once the work has other contributors (each a copyright holder), “nobody” starts including you. 24 | 25 | CAUTION: As a consumer, if you find software that doesn’t have a license, that generally means you have no permission from the creators of the software to use, modify, or share the software. Although a code host such as GitHub may allow you to view and fork the code, this does not imply that you are permitted to use, modify, or share the software for any purpose. Your options are: Ask the maintainers nicely to add a license, Don’t use the software, Negotiate a private license with a lawyer. 26 | -------------------------------------------------------------------------------- /src/do/do-licensing-es.adoc: -------------------------------------------------------------------------------- 1 | === Licenciamiento 2 | 3 | No es requerido seleccionar una licencia, sin embargo, al hacerlo, estás seleccionando "Sin Licencia" lo que por defecto te llevará a los https://help.github.com/articles/github-terms-of-service/[Términos y Condiciones] de GitHub. GitHub ha creado un gran sitio web informativo para ayudarte a elegir una http://choosealicense.com[licencia] 4 | 5 | A continuación ejemplos de http://choosealicense.com["Escoge una licencia de código abierto"]: 6 | 7 | [quote, Escoge una Licencia, Licencia MIT] 8 | La Licencia MIT es una licencia permisiva que es breve y va directo al grano. Permite a la gente hacer lo que deseen con tu código siempre y cuando recibas atribución y no te hagan responsable. 9 | 10 | NOTE: jQuery, .NET Core, y Rails utilizan la Licencia MIT. 11 | 12 | [quote, Escoge una Licencia, Licencia Apache 2.0] 13 | La Licencia Apache 2.0 es una licencia permisiva similar a la licencia del MIT, pero además provee una otorgamiento expreso de derechos de patente de los colaboradores a los usuarios. 14 | 15 | NOTE: Android, Apache, y Swift utilizan la Licencia Apache 2.0. 16 | 17 | [quote, Escoge una Licencia, GNU GPLv3] 18 | La GNU GPLv3 es una licencia copyleft que requiere que cualquiera que distribuya tu código o un trabajo derivado haga lo mismo con el código fuente bajo los mismos términos, y también provee una otorgamiento expreso de derechos de patente de los colaboradores a los usuarios. 19 | 20 | NOTE: Bash, GIMP, y Privacy Badger utilizan la Licencia GNU GPLv3. 21 | 22 | [quote, Escoge una Licencia, Sin Licencia] 23 | Cuando realizas un trabajo creativo (que incluye código), tu trabajo está bajo copyright exclusivo por defecto. A menos que incluyas una licencia que especifique lo contrario, nadie más puede usar, copiar, distribuir, o modificar tu trabajo sin correr el riesgo de bajas, sacudidas o litigios. Una vez que tu trabajo tiene otros colaboradores (cada uno un titular de derechos de autor), "nadie" comienza a incluirte a ti. 24 | 25 | CAUTION: Como consumidor, si encuentras software que no contiene una licencia, eso generalmente significa que no tienes permiso de los creadores para usar, modificar, o compartir el software. A pesar de que un alojador de código como GitHub pueda permitirme ver y bifurcar -fork- el código, esto no implica que tú tienes el permiso de usar, modificar, o compartir el software para ningún propósito. Tus opciones son: Pide amablemente a los desarrolladores que agreguen una licencia, no utilices el software, negocia una licencia privada con un abogado. 26 | -------------------------------------------------------------------------------- /src/index.adoc: -------------------------------------------------------------------------------- 1 | = Open Source Tips 2 | By Eddie Jaoude 3 | :toc: 4 | 5 | :author: Eddie Jaoude 6 | :twitter: https://twitter.com/eddiejaoude 7 | :date: 2016 8 | :version: 0.1.0 9 | :repo: https://github.com/eddiejaoude/book-open-source-tips 10 | :imagesdir: images 11 | :docinfo1: 12 | 13 | [abstract] 14 | == Abstract 15 | 16 | This book contains some common DOs & DON'Ts for Open Source software. 17 | 18 | [preface] 19 | == Preface 20 | 21 | The Open Source community is thriving. Each day the number of Open Source projects grows, as does the army of contributors that maintain them. While this is exciting for the industry, it can be daunting as a developer new to the community. This book aims to provide some tips for newcomers to help them avoid the pitfalls of Open Source development and learn from the community's collective wisdom. 22 | 23 | As the ancient proverb goes, "_Time and tide [and technology] wait for no man_". And to the best of our ability, neither will this book. Remember to check the version number for updates! We're currently on v{version}. 24 | 25 | We would love your help in keeping this book updated. Your comments, suggestions and pull requests are most welcome. You can find the repository on GitHub: {repo}. 26 | 27 | If you have any questions, please contact the author, {author} on {twitter}. 28 | 29 | <<< 30 | == Introduction 31 | 32 | Open Source is dominating the software industry. Its champions include well known organisations like Facebook, Twitter, Netflix, LinkedIn and Google (Android/Chrome), but more significantly, an army of passionate individual developers around the world. Their efforts have impacted almost every part of computer science, culminating in millions of open source projects, with billions of lines of code! 33 | 34 | While this abundant ecosystem has been of huge benefit to the whole industry, it can also make it difficult for newcomers to know where to start. If you're a newcomer, you might be faced with questions such as _"How can I contribute to the Open Source community?"_ Or, _"How do I choose between so many competing projects?"_. The following DOs and DON'Ts aim to address some of those basic questions, plus some pointers for aspiring Open Source developers. 35 | 36 | Let's dive right in. 37 | 38 | TIP: Projects not made public at the beginning are at higher risk of having private credentials committed in the history. Therefore it is highly recommended to make projects public from the start, stating they are not finished is not an excuse as they will never be finished. If public from day one, then the right mindset is used and thus reduces the risk. 39 | 40 | 41 | <<< 42 | == DOs 43 | 44 | include::do.adoc[] 45 | 46 | <<< 47 | == DON'Ts 48 | 49 | include::dont.adoc[] 50 | 51 | <<< 52 | == Appendix 53 | 54 | include::appendix.adoc[] 55 | -------------------------------------------------------------------------------- /src/index-es.adoc: -------------------------------------------------------------------------------- 1 | = Consejos para el Código Abierto 2 | By Eddie Jaoude 3 | :toc: 4 | 5 | :author: Eddie Jaoude 6 | :twitter: https://twitter.com/eddiejaoude 7 | :date: 2016 8 | :version: 0.1.0 9 | :repo: https://github.com/eddiejaoude/book-open-source-tips 10 | :imagesdir: images 11 | :docinfo1: 12 | 13 | [abstract] 14 | == Resumen 15 | 16 | Este libro contiene algunas cosas que se deben y no se deben hacer para el software de Código Abierto. 17 | 18 | [preface] 19 | == Prefacio 20 | 21 | La comunidad de Código Abierto está prosperando. Cada día crece el número de proyectos de Código Abierto, al igual que el ejército de contribuyentes que los mantienen. Si bien esto es emocionante para la industria, puede ser desalentador para un desarrollador nuevo en la comunidad. Este libro tiene como objetivo proporcionar algunos consejos para los recién llegados para ayudarlos a evitar las trampas del desarrollo de Código Abierto y aprender de la sabiduría colectiva de la comunidad. 22 | 23 | Como dice el proverbio antiguo, "_El tiempo y la marea [y la tecnología] no esperan a nadie_". Y para lo mejor de nuestra capacidad, tampoco este libro. ¡Recuerde verificar el número de la versión para las actualizaciones! Estamos actualmente en la versión {version}. 24 | 25 | Nos encantaría su ayuda para mantener este libro actualizado. Sus comentarios, sugerencias y pull requests son bienvenidos. Puede encontrar el repositorio en GitHub: {repo}. 26 | 27 | Si tiene alguna pregunta, por favor comuníquese con el autor, {author} en {twitter}. 28 | 29 | <<< 30 | == Introducción 31 | 32 | El Código Abierto está dominando la industria del software. Sus campeones incluyen conocidas organizaciones como Facebook, Twitter, Netflix, LinkedIn y Google (Android/Chrome), pero más importantemente, un ejército de desarrolladores individuales apasionados alrededor del mundo. Sus esfuerzos han impactado casi todas las partes de la ciencia de la computación, culminando en millones de proyectos de código abierto, ¡con miles de millones de líneas de código! 33 | 34 | Si bien este ecosistema abundante ha sido de gran beneficio para toda la industria, también puede hacer que sea difícil para los recién llegados saber por dónde empezar. Si usted es un recién llegado, es posible que se enfrente a preguntas tales como _"¿Cómo puedo contribuir a la comunidad de código abierto?"_ O, _"¿Cómo elijo entre tantos proyectos en competencia?"_. Los siguientes puntos a abordan algunas de esas preguntas básicas, además de algunos consejos para aspirantes a desarrolladores de código abierto. 35 | 36 | Vamos a sumergirnos en esto. 37 | 38 | SUGERENCIA: Los proyectos que no se hacen públicos al principio tienen un mayor riesgo de tener credenciales privadas comprometidas en la historia. Por lo tanto, se recomienda altamente hacer públicos los proyectos desde el principio, y afirmar que no están terminados no es una excusa, ya que nunca se terminarán. Si es público desde el primer día, se usa la mentalidad correcta y, por lo tanto, se reduce el riesgo. 39 | 40 | <<< 41 | == Qué Hacer 42 | 43 | include::do-es.adoc[] 44 | 45 | <<< 46 | == Qué No Hacer 47 | 48 | include::dont-es.adoc[] 49 | 50 | <<< 51 | == Apéndice 52 | 53 | include::appendix.adoc[] 54 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. 6 | 7 | ## Our Standards 8 | 9 | Examples of behavior that contributes to creating a positive environment include: 10 | 11 | * Using welcoming and inclusive language 12 | * Being respectful of differing viewpoints and experiences 13 | * Gracefully accepting constructive criticism 14 | * Focusing on what is best for the community 15 | * Showing empathy towards other community members 16 | 17 | Examples of unacceptable behavior by participants include: 18 | 19 | * The use of sexualized language or imagery and unwelcome sexual attention or advances 20 | * Trolling, insulting/derogatory comments, and personal or political attacks 21 | * Public or private harassment 22 | * Publishing others' private information, such as a physical or electronic address, without explicit permission 23 | * Other conduct which could reasonably be considered inappropriate in a professional setting 24 | 25 | ## Our Responsibilities 26 | 27 | Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. 28 | 29 | Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. 30 | 31 | ## Scope 32 | 33 | This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. 34 | 35 | ## Enforcement 36 | 37 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at eddie@jaoudestudios.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. 38 | 39 | Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. 40 | 41 | ## Attribution 42 | 43 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] 44 | 45 | [homepage]: http://contributor-covenant.org 46 | [version]: http://contributor-covenant.org/version/1/4/ 47 | -------------------------------------------------------------------------------- /src/index-fil.adoc: -------------------------------------------------------------------------------- 1 | = Mga Paaalalahanan sa Open Source 2 | By Eddie Jaoude 3 | :toc: 4 | 5 | :author: Eddie Jaoude 6 | :twitter: https://twitter.com/eddiejaoude 7 | :date: 2016 8 | :version: 0.1.0 9 | :repo: https://github.com/eddiejaoude/book-open-source-tips 10 | :imagesdir: images 11 | :docinfo1: 12 | 13 | [abstract] 14 | == Buod 15 | 16 | Ang aklat na ito ay naglalaman ng mga karaniwang DAPAT at HINDI DAPAT GAWIN para sa Open Source na software. 17 | 18 | [preface] 19 | == Paunang Salita 20 | 21 | Ang komunidad ng Open Source ay patuloy na lumalago. Sa bawat araw na dumarami ang bilang ng mga proyektong Open Source, gayundin ang hukbo ng mga nag-aambag para panatilihin sila. Bagaman nakakapanabik ito para sa industriya, maaari itong maging katakot-takot para sa isang bagong tagabuo sa komunidad. Ang aklat na ito ay naglalayon na magbigay ng iilang mga paaalalahanan para sa mga baguhan upang makatulong sa kanila na iwasan ang mga patibong sa pagbuo ng Open Source at para matuto mula sa pangkalahatang kaalaman ng komunidad. 22 | 23 | Ika nga sa lumang kawikaan, "_Ang oras at ang alon [at teknolohiya] ay hindi naghihintay sa sinumang tao_". At sa abot ng aming makakaya, maging ang aklat ding ito. Tandaang tingnan ang bilang ng bersyon para sa mga update! Kami’y kasalukuyang nasa v{version}. 24 | 25 | Lubos naming ikagagalak ang inyong tulong upang mapanatiling naka-update ang aklat na ito. Ang inyong mga komento, suhestiyon at pull requests ay malugod naming tinatanggap. Maaari niyong hanapin ang repository sa Github: {repo}. 26 | 27 | Kung may iba pa kayong mga katanungan, mangyari lamang na makipag-ugnay sa may-akda na si {author} sa {twitter}. 28 | 29 | <<< 30 | == Panimula 31 | 32 | Nangingibabaw ang Open Source sa industriya ng software. Ang mga kampeon nito'y pinabibilangan ng mga tanyag na organisasyon tulad ng Facebook, Twitter, Netflix, LinkedIn at Google (Android/Chrome), ngunit ang mas mahalaga, ang hukbo ng mga dedikadong indibidwal na tagabuo sa buong mundo. Ang kanilang mga pagsisikap ay nagkaroon ng epekto sa halos bawat bahagi ng computer science, nagresulta sa milyun-milyong open source na proyekto na may bilyun-bilyong mga linya ng code! 33 | 34 | Habang ang masaganang ecosystem na ito ay nagbigay ng malaking tulong sa buong industriya, maaari rin itong magpahirap sa mga baguhan na hindi alam kung saan magsisimula. Kung ikaw ay isang baguhan, maaari mong harapin ang mga katanungang _"Paano ako makakaambag sa komunidad ng Open Source?"_ O, _"Paano ako pipili sa pagitan ng napakaraming nakikipagkompetensiyang proyekto?"_. Ang mga sumusunod na mga DAPAT at HINDI DAPAT GAWIN ay naglalayon na masagot ang mga katanungang iyon, pati na rin ang ibang mga payo para sa nagbabalak na maging tagabuo ng Open Source. 35 | 36 | Tara na't sisirin natin ito. 37 | 38 | PAALALA: Ang mga proyektong hindi isinapubliko sa simula ay may mas mataas na pagkakataong ipagkatiwala ang mga pribadong kredensyal sa kasaysayan, kung kaya't mas nirerekomendang gawing pampubliko ang mga proyekto sa simula pa lang. Ang pagsasaad na sila ay hindi pa tapos ay hindi isang dahilan, dahil kailanman, sila ay hindi matatapos. Kung isinapubliko sa simula pa lamang, pinaparating lang noon na ang tamang pananaw ang ginamit kaya naman mababawasan ang panganib. 39 | 40 | 41 | <<< 42 | == Mga Dapat Gawin 43 | 44 | include::do-fil.adoc[] 45 | 46 | <<< 47 | == Mga Hindi Dapat Gawin 48 | 49 | include::dont.adoc[] 50 | 51 | <<< 52 | == Apendiks 53 | 54 | include::appendix.adoc[] 55 | -------------------------------------------------------------------------------- /.github/CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, gender identity and expression, level of experience, 9 | nationality, personal appearance, race, religion, or sexual identity and 10 | orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at eddie@jaoudestudios.com. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at [http://contributor-covenant.org/version/1/4][version] 72 | 73 | [homepage]: http://contributor-covenant.org 74 | [version]: http://contributor-covenant.org/version/1/4/ 75 | -------------------------------------------------------------------------------- /src/appendix.adoc: -------------------------------------------------------------------------------- 1 | === Acronyms 2 | 3 | .Acronyms 4 | |=== 5 | |Acronym |Description |Notes 6 | 7 | |TDD 8 | |Test Driven Development 9 | |GOOD! https://en.wikipedia.org/wiki/Test-driven_developmentp[Wikipedia] 10 | 11 | |BDD 12 | |Behaviour Driven Development 13 | |GOOD! https://en.wikipedia.org/wiki/Behavior-driven_development[Wikipedia] 14 | 15 | |CVDD 16 | |CV Driven Development 17 | |BAD! 18 | |=== 19 | 20 | === Resources 21 | 22 | TIP: Suggestions welcome...read more at how to https://github.com/eddiejaoude/book-open-source-tips/blob/master/.github/CONTRIBUTING.md[contribute] 23 | 24 | [quote, Contributing to Open Source on GitHub, https://guides.github.com/activities/contributing-to-open-source/] 25 | A great way to get involved in open source is to contribute to the existing projects you’re using. GitHub is home to more than 5 million open source projects. There are projects for every skill set like recipes, HTML/CSS, Ruby, Astrophysics and many more. This guide will cover what you might find in a typical project and how to make a great contribution. 26 | 27 | [quote, The Beginner’s Guide to Contributing to Open Source Projects, https://blog.newrelic.com/2014/05/05/open-source_gettingstarted/] 28 | Open source works by having many people contribute to the creation and maintenance of software. Thing is, it works well only when people are actually contributing. Successful open source projects thrive on a wide variety of contributions from people with all levels of coding skills and commitment. If just one person fixes a compiler warning, closes a bug, or adds to the documentation, pretty soon you’re talking real progress. For many people, the hardest part is just getting started. So here are some suggested ways you can begin contributing right away, at whatever level is most comfortable for you. 29 | 30 | [quote, How to contribute to an open source project on GitHub, http://blog.davidecoppola.com/2016/11/howto-contribute-to-open-source-project-on-github/] 31 | GitHub is the home of many popular open source projects like Ruby on Rails, jQuery, Docker, Go and many others. The way people (usually) contribute to an open source project on GitHub is using pull requests. A pull request is basically a patch which includes more information and allows members to discuss it on the website. 32 | 33 | [quote, A Beginner’s Very Bumpy Journey Through The World of Open Source, https://medium.freecodecamp.com/a-beginners-very-bumpy-journey-through-the-world-of-open-source-4d108d540b39#.an82epenf] 34 | It’s okay to not know everything, and take one step at a time to learn something new. Don’t waste a lot of time choosing the “right” project. If you know a project or a organization with a beginner-friendly community, just start there. A huge shout-out to all the open source maintainers who have been super responsive and encourage of new contributors. You are helping newcomers navigate huge code bases and contribute in maybe a small yet meaningful ways. Your efforts are truly appreciated and needed. 35 | 36 | [quote, How to care for the community over the code, https://opensource.com/article/16/12/community-over-code] 37 | You want to focus on the building blocks for your community before you get too deep in the code. "We'll do it right later" doesn't always work out well. If you don't make governance decisions now, things can fall apart, or if you make the wrong decision, it could turn off potential community members going forward. 38 | 39 | [quote, Web Accessibility Checklist, http://a11yproject.com/checklist.html] 40 | For many web developers, accessibility is complex and somewhat difficult. The Accessibility Project understands that and we want to help to make web accessibility easier for front end developers to implement. Blind and visually impaired make up 285,000,000 people according to the World Health Organization (June 2012) with 39,000,000 categorized as legally blind and the remaining 246,000,000 visually impaired. Deaf and hearing impaired make up 275,000,000 (2004) in the moderate-to-profound hearing impairment category. 41 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![DashboardHub](https://img.shields.io/badge/DashboardHub-Open%20Source%20Book-orange.svg)](https://pipeline.dashboardhub.io/environments/f39a2d40-2045-11e8-a435-ade829eb4121) 2 | 3 | # Open Source Tips 4 | 5 | Open Source book on Open Source Tips 6 | 7 | | Language | Status | Link | 8 | | :--- | :--- | :--- | 9 | | English | - | https://eddiejaoude.github.io/book-open-source-tips/ | 10 | | Spanish | In progress | https://eddiejaoude.github.io/book-open-source-tips/index-es.html | 11 | | Filipino | In progress | https://eddiejaoude.github.io/book-open-source-tips/index-fil.html | 12 | 13 | This book contains some common **DOs** & **DON'Ts** for Open Source software. 14 | 15 | The Open Source community is thriving. Each day the number of Open Source projects grow, as does the army of contributors that maintain them. While this is exciting for the industry, it can be daunting as a developer new to the community. This book aims to provide some tips for newcomers to help them avoid the pitfalls of Open Source development and learn from the community's collective wisdom. 16 | 17 | As the ancient proverb goes, _Time and tide [and technology] wait for no man_. And to the best of our ability, neither will this book. Remember to check the version number for updates! 18 | 19 | We would love your help in keeping this book updated. Your comments, suggestions, and pull requests are most welcome. 20 | 21 | Open Source is dominating the software industry. Its champions include well-known organisations like Facebook, Twitter and Netflix, but more significantly, an army of passionate individual developers around the world. Their efforts have impacted almost every part of computer science, culminating in millions of open source projects, with billions of lines of code! 22 | 23 | While this abundant ecosystem has been of huge benefit to the whole industry, it can also make it difficult for newcomers to know where to start. If you're a newcomer, you might be faced with questions such as _"How can I contribute to the Open Source community?"_ Or, _"How do I choose between so many competing projects?"_ The following DOs and DON'Ts aim to address some of those basic questions, and offer some pointers to aspiring Open Source developers. 24 | 25 | [Let's dive right in](https://eddiejaoude.github.io/book-open-source-tips/). 26 | 27 | All changes in `master` branch are automatically deployed to the above URL. 28 | 29 | ## Code of Conduct 30 | 31 | * [Code of Conduct](.github/CODE_OF_CONDUCT.md) 32 | 33 | ## Dependencies 34 | 35 | * [Ascii Doctor](http://asciidoctor.org) 36 | 37 | ## Quick Start 38 | 39 | ### Install 40 | 41 | * AsciiDoctor (html) 42 | 43 | ```bash 44 | gem install asciidoctor 45 | ``` 46 | 47 | * AciiDoctor (pdf) 48 | 49 | ```bash 50 | gem install --pre asciidoctor-pdf 51 | ``` 52 | 53 | * Atom preview [plugin](https://atom.io/packages/asciidoc-preview) (optional) 54 | 55 | ```bash 56 | apm install asciidoc-preview 57 | ``` 58 | 59 | * VS Code preview [plugin](https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode) (optional) 60 | 61 | Launch VS Code Quick Open (Windows: `ctrl+p`, Mac: `cmd+p`), paste the following command, and press enter: 62 | 63 | ```bash 64 | ext install joaompinto.asciidoctor-vscode 65 | ``` 66 | 67 | ### Source code 68 | 69 | Source code is in `src/` directory. 70 | 71 | ### Generate html, pdf etc 72 | 73 | * To generate the output in **html** & **pdf**: 74 | 75 | ```bash 76 | make 77 | ``` 78 | 79 | ![Generated pdf](https://cloud.githubusercontent.com/assets/624760/20028256/e127f148-a345-11e6-9871-5e40a7c73edb.png) 80 | 81 | ![Generated html](https://cloud.githubusercontent.com/assets/624760/20028253/cfd770c6-a345-11e6-8552-88904ecca9dc.png) 82 | 83 | 84 | ### Live Server in Codespace 85 | 86 | If you are opening up in GitHub Codespace or VSCode with a DevContainer, then Live Server extension is installed and the port mapping to 5500 setup. Just start liveshare through the command pallet or with 'alt + l then alt + o' then go to remote explorer and open the Live Server in a new browser tab. 87 | -------------------------------------------------------------------------------- /config/pdf-theme.yml: -------------------------------------------------------------------------------- 1 | font: 2 | catalog: 3 | # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols 4 | Noto Serif: 5 | normal: notoserif-regular-subset.ttf 6 | bold: notoserif-bold-subset.ttf 7 | italic: notoserif-italic-subset.ttf 8 | bold_italic: notoserif-bold_italic-subset.ttf 9 | # M+ 1mn supports ASCII and the circled numbers used for conums 10 | M+ 1mn: 11 | normal: mplus1mn-regular-ascii-conums.ttf 12 | bold: mplus1mn-bold-ascii.ttf 13 | italic: mplus1mn-italic-ascii.ttf 14 | bold_italic: mplus1mn-bold_italic-ascii.ttf 15 | # M+ 1p supports Latin, Latin-1 Supplement, Latin Extended, Greek, Cyrillic, Vietnamese, Japanese & an assortment of symbols 16 | # It also provides arrows for ->, <-, => and <= replacements in case these glyphs are missing from font 17 | M+ 1p Fallback: 18 | normal: mplus1p-regular-fallback.ttf 19 | bold: mplus1p-regular-fallback.ttf 20 | italic: mplus1p-regular-fallback.ttf 21 | bold_italic: mplus1p-regular-fallback.ttf 22 | fallbacks: 23 | - M+ 1p Fallback 24 | page: 25 | background_color: ffffff 26 | layout: portrait 27 | margin: [0.5in, 0.67in, 0.67in, 0.67in] 28 | # margin_inner and margin_outer keys are used for recto/verso print margins when media=press 29 | margin_inner: 0.75in 30 | margin_outer: 0.59in 31 | size: A4 32 | base: 33 | align: justify 34 | # color as hex string (leading # is optional) 35 | font_color: 333333 36 | # color as RGB array 37 | #font_color: [51, 51, 51] 38 | # color as CMYK array (approximated) 39 | #font_color: [0, 0, 0, 0.92] 40 | #font_color: [0, 0, 0, 92%] 41 | font_family: Noto Serif 42 | # choose one of these font_size/line_height_length combinations 43 | #font_size: 14 44 | #line_height_length: 20 45 | #font_size: 11.25 46 | #line_height_length: 18 47 | #font_size: 11.2 48 | #line_height_length: 16 49 | font_size: 10.5 50 | #line_height_length: 15 51 | # correct line height for Noto Serif metrics 52 | line_height_length: 12 53 | #font_size: 11.25 54 | #line_height_length: 18 55 | line_height: $base_line_height_length / $base_font_size 56 | font_size_large: round($base_font_size * 1.25) 57 | font_size_small: round($base_font_size * 0.85) 58 | font_size_min: $base_font_size * 0.75 59 | font_style: normal 60 | border_color: eeeeee 61 | border_radius: 4 62 | border_width: 0.5 63 | # FIXME vertical_rhythm is weird; we should think in terms of ems 64 | #vertical_rhythm: $base_line_height_length * 2 / 3 65 | # correct line height for Noto Serif metrics (comes with built-in line height) 66 | vertical_rhythm: $base_line_height_length 67 | horizontal_rhythm: $base_line_height_length 68 | # QUESTION should vertical_spacing be block_spacing instead? 69 | vertical_spacing: $vertical_rhythm 70 | link: 71 | font_color: 428bca 72 | # literal is currently used for inline monospaced in prose and table cells 73 | literal: 74 | font_color: b12146 75 | font_family: M+ 1mn 76 | menu_caret_content: " \u203a " 77 | heading: 78 | align: left 79 | #font_color: 181818 80 | font_color: $base_font_color 81 | font_family: $base_font_family 82 | font_style: bold 83 | # h1 is used for part titles (book doctype only) 84 | h1_font_size: floor($base_font_size * 2.6) 85 | # h2 is used for chapter titles (book doctype only) 86 | h2_font_size: floor($base_font_size * 2.15) 87 | h3_font_size: round($base_font_size * 1.7) 88 | h4_font_size: $base_font_size_large 89 | h5_font_size: $base_font_size 90 | h6_font_size: $base_font_size_small 91 | #line_height: 1.4 92 | # correct line height for Noto Serif metrics (comes with built-in line height) 93 | line_height: 1 94 | margin_top: $vertical_rhythm * 0.4 95 | margin_bottom: $vertical_rhythm * 0.9 96 | title_page: 97 | align: right 98 | logo: 99 | top: 10% 100 | title: 101 | top: 55% 102 | font_size: $heading_h1_font_size 103 | font_color: 999999 104 | line_height: 0.9 105 | subtitle: 106 | font_size: $heading_h3_font_size 107 | font_style: bold_italic 108 | line_height: 1 109 | authors: 110 | margin_top: $base_font_size * 1.25 111 | font_size: $base_font_size_large 112 | font_color: 181818 113 | revision: 114 | margin_top: $base_font_size * 1.25 115 | block: 116 | margin_top: 0 117 | margin_bottom: $vertical_rhythm 118 | caption: 119 | align: left 120 | font_size: $base_font_size * 0.95 121 | font_style: italic 122 | # FIXME perhaps set line_height instead of / in addition to margins? 123 | margin_inside: $vertical_rhythm / 3 124 | #margin_inside: $vertical_rhythm / 4 125 | margin_outside: 0 126 | lead: 127 | font_size: $base_font_size_large 128 | line_height: 1.4 129 | abstract: 130 | font_color: 5c6266 131 | font_size: $lead_font_size 132 | line_height: $lead_line_height 133 | font_style: italic 134 | first_line_font_style: bold 135 | title: 136 | align: center 137 | font_color: $heading_font_color 138 | font_family: $heading_font_family 139 | font_size: $heading_h4_font_size 140 | font_style: $heading_font_style 141 | admonition: 142 | column_rule_color: $base_border_color 143 | column_rule_width: $base_border_width 144 | padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm] 145 | #icon: 146 | # tip: 147 | # name: fa-lightbulb-o 148 | # stroke_color: 111111 149 | # size: 24 150 | label: 151 | text_transform: uppercase 152 | font_style: bold 153 | blockquote: 154 | font_color: $base_font_color 155 | font_size: $base_font_size_large 156 | border_color: $base_border_color 157 | border_width: 5 158 | # FIXME disable negative padding bottom once margin collapsing is implemented 159 | padding: [0, $horizontal_rhythm, $block_margin_bottom * -0.75, $horizontal_rhythm + $blockquote_border_width / 2] 160 | cite_font_size: $base_font_size_small 161 | cite_font_color: 999999 162 | # code is used for source blocks (perhaps change to source or listing?) 163 | code: 164 | font_color: $base_font_color 165 | font_family: $literal_font_family 166 | font_size: ceil($base_font_size) 167 | padding: $code_font_size 168 | line_height: 1.25 169 | background_color: f5f5f5 170 | border_color: cccccc 171 | border_radius: $base_border_radius 172 | border_width: 0.75 173 | conum: 174 | font_family: M+ 1mn 175 | font_color: $literal_font_color 176 | font_size: $base_font_size 177 | line_height: 4 / 3 178 | example: 179 | border_color: $base_border_color 180 | border_radius: $base_border_radius 181 | border_width: 0.75 182 | background_color: transparent 183 | # FIXME reenable padding bottom once margin collapsing is implemented 184 | padding: [$vertical_rhythm, $horizontal_rhythm, 0, $horizontal_rhythm] 185 | image: 186 | align: left 187 | prose: 188 | margin_top: $block_margin_top 189 | margin_bottom: $block_margin_bottom 190 | sidebar: 191 | border_color: $page_background_color 192 | border_radius: $base_border_radius 193 | border_width: $base_border_width 194 | background_color: eeeeee 195 | # FIXME reenable padding bottom once margin collapsing is implemented 196 | padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25] 197 | title: 198 | align: center 199 | font_color: $heading_font_color 200 | font_family: $heading_font_family 201 | font_size: $heading_h4_font_size 202 | font_style: $heading_font_style 203 | thematic_break: 204 | border_color: $base_border_color 205 | border_style: solid 206 | border_width: $base_border_width 207 | margin_top: $vertical_rhythm * 0.5 208 | margin_bottom: $vertical_rhythm * 1.5 209 | description_list: 210 | term_font_style: italic 211 | term_spacing: $vertical_rhythm / 4 212 | description_indent: $horizontal_rhythm * 1.25 213 | outline_list: 214 | indent: $horizontal_rhythm * 1.5 215 | #marker_font_color: 404040 216 | # NOTE outline_list_item_spacing applies to list items that do not have complex content 217 | item_spacing: $vertical_rhythm / 2 218 | table: 219 | background_color: $page_background_color 220 | #head_background_color: 221 | #head_font_color: $base_font_color 222 | head_font_style: bold 223 | even_row_background_color: f9f9f9 224 | #odd_row_background_color: 225 | foot_background_color: f0f0f0 226 | border_color: dddddd 227 | border_width: $base_border_width 228 | # HACK accounting for line-height 229 | cell_padding: [3, 3, 6, 3] 230 | toc: 231 | indent: $horizontal_rhythm 232 | line_height: 1.4 233 | dot_leader: 234 | #content: ". " 235 | font_color: a9a9a9 236 | #levels: 2 3 237 | # NOTE in addition to footer, header is also supported 238 | header: 239 | font_size: $base_font_size_small 240 | # NOTE if background_color is set, background and border will span width of page 241 | border_color: dddddd 242 | border_width: 0.25 243 | height: $base_line_height_length * 2.5 244 | line_height: 1 245 | padding: [$base_line_height_length / 2, 1, 0, 1] 246 | vertical_align: center 247 | #image_vertical_align: or 248 | # additional attributes for content: 249 | # * {page-count} 250 | # * {page-number} 251 | # * {document-title} 252 | # * {document-subtitle} 253 | # * {chapter-title} 254 | # * {section-title} 255 | # * {section-or-chapter-title} 256 | recto: 257 | #columns: "<50% =0% >50%" 258 | right: 259 | # content: '{page-number}' 260 | #content: '{section-or-chapter-title} | {page-number}' 261 | #content: '{document-title} | {page-number}' 262 | center: 263 | content: '{section-or-chapter-title} | v{version}' 264 | verso: 265 | #columns: $footer_recto_columns 266 | # left: 267 | # content: '{page-number}' 268 | #content: '{page-number} | {chapter-title}' 269 | center: 270 | content: '{section-or-chapter-title} | v{version}' 271 | footer: 272 | font_size: $base_font_size_small 273 | # NOTE if background_color is set, background and border will span width of page 274 | border_color: dddddd 275 | border_width: 0.25 276 | height: $base_line_height_length * 2.5 277 | line_height: 1 278 | padding: [$base_line_height_length / 2, 1, 0, 1] 279 | vertical_align: top 280 | #image_vertical_align: or 281 | # additional attributes for content: 282 | # * {page-count} 283 | # * {page-number} 284 | # * {document-title} 285 | # * {document-subtitle} 286 | # * {chapter-title} 287 | # * {section-title} 288 | # * {section-or-chapter-title} 289 | recto: 290 | #columns: "<50% =0% >50%" 291 | # right: 292 | # content: '{page-number}' 293 | #content: '{section-or-chapter-title} | {page-number}' 294 | #content: '{document-title} | {page-number}' 295 | # center: 296 | # content: '{document-title} | {page-number}' 297 | left: 298 | content: '{repo}' 299 | right: 300 | content: '{document-title} | {page-number}' 301 | verso: 302 | #columns: $footer_recto_columns 303 | left: 304 | content: '{repo}' 305 | #content: '{page-number} | {chapter-title}' 306 | # center: 307 | # content: '{document-title} | {page-number}' 308 | right: 309 | content: '{document-title} | {page-number}' 310 | --------------------------------------------------------------------------------