diff --git a/content/contributing/challenge-coins/contents.lr b/content/contributing/challenge-coins/contents.lr index 3f0c10e12e..2764279c4a 100644 --- a/content/contributing/challenge-coins/contents.lr +++ b/content/contributing/challenge-coins/contents.lr @@ -8,33 +8,43 @@ summary: What is a challenge coin, and why do you want one? --- body: -Challenge Coins are a military tradition, which is said to originate at the start of last century. They were distributed based on merit in events or for other reasons, and hold deep personal value. +Challenge Coins are a military tradition, which is said to originate at the +start of last century. They were distributed based on merit in events or for +other reasons, and hold deep personal value. -To find out more about Challenge Coins, you can listen to the `99% Invisible`_ podcast about them, or read up about them on `Wikipedia`_. +To find out more about Challenge Coins, you can listen to the `99% Invisible`_ +podcast about them, or read up about them on `Wikipedia`_. .. figure:: /contributing/challenge-coins/challenge-coin.jpg :alt: The front and back of the BeeWare Challenge Coin. *The front and back of the BeeWare Challenge Coin.* -The BeeWare Challenge Coins are die cast, 4.5cm (1 3/4") in diameter, and are made of a nickel/zinc alloy with enamel highlights. +The BeeWare Challenge Coins are die cast, 4.5cm (1 3/4") in diameter, and are +made of a nickel/zinc alloy with enamel highlights. Any contribution to the BeeWare project earns you a coin. -It doesn't have to be a code contribution: a documentation update counts. A blog post. Helping someone during a sprint with their contribution. +It doesn't have to be a code contribution: a documentation update counts. A +blog post. Helping someone during a sprint with their contribution. -And as an additional incentive, for those people who help others get their challenge coins, we have a second coin: the Yak Herder +And as an additional incentive, for those people who help others get their +challenge coins, we have a second coin: the Yak Herder .. figure:: /contributing/challenge-coins/yak-herder-coin.jpg :alt: The front and back of the BeeWare Yak Herder Coin. *The front and back of the BeeWare Yak Herder Coin.* -The first run of 100 BeeWare Challenge Coins were commissioned thanks to financial support from `MaxCDN`_. They also wrote an `article about BeeWare`_ on their blog. +The first run of 100 BeeWare Challenge Coins were commissioned thanks to +financial support from `MaxCDN`_. They also wrote an `article about BeeWare`_ +on their blog. -`Revolution Systems`_ provided the funding for the second pressing of the BeeWare challenge coins. +`Revolution Systems`_ provided the funding for the second pressing of the +BeeWare challenge coins. -`Github`_ provided the funding for the first pressing of the BeeWare Yak Herder challenge coins. +`Github`_ provided the funding for the first pressing of the BeeWare Yak Herder +challenge coins. .. figure:: /contributing/challenge-coins/sprint-coin.jpg :alt: One happy BeeWare coin recipient. Photo by Atom Images diff --git a/content/contributing/core-team/contents.lr b/content/contributing/core-team/contents.lr index 1a33a54556..c9db2a88db 100644 --- a/content/contributing/core-team/contents.lr +++ b/content/contributing/core-team/contents.lr @@ -58,7 +58,6 @@ Bee-nevolent Dictator for Now (BDFN): `Russell Keith-Magee `__. Everyone can contribute to open source, and we're here to show you how. +If you're new to the project (or even entirely new to open source in general), +the best place to start is `here `__. Everyone +can contribute to open source, and we're here to show you how. .. _First-time Contributors: /contributing/how/first-time/ @@ -31,7 +33,8 @@ of interest. There will usually be a couple of tickets with known problems; any ticket is a candidate for being fixed. If you're a first time contributor, some tickets are also tagged as -`[good first issue] `__. +`[good first issue] +`__. These are special issues that have been selected because they're relatively simple introductions to the project, and the BeeWare team will mentor any first time contributor in committing a patch for @@ -40,22 +43,30 @@ one of these issues. Platform Usage --------------- -Do you use Windows or various flavours of Linux? Are you able to install a project or application on your system? Did you run into any problems? +Do you use Windows or various flavours of Linux? Are you able to install a +project or application on your system? Did you run into any problems? -If so, please update the documentation to show how you were able to get it to work, or log an issue if you've found a bug that you can't fix. +If so, please update the documentation to show how you were able to get it to +work, or log an issue if you've found a bug that you can't fix. Documentation -------------- -Is the documentation up to date? Do you think things could be worded differently? Are there missing sections? Do you have an idea for a tutorial that could be written? Please submit a Pull Request! +Is the documentation up to date? Do you think things could be worded +differently? Are there missing sections? Do you have an idea for a tutorial +that could be written? Please submit a pull request! + +Is there anything wrong or missing from this website? Please feel free to `make +edits `__ and submit a pull +request! Help translate and update this Website --------------------------------------- -Is there anything wrong or missing from this website? Please feel free to `make edits `__ and submit a pull request! - -Want to help translate or update the content of this website? Visit the `translations section `__. - +Do you speak a language other than English, and would like to help others +have better access to BeeWare documentation? Visit the +`translations section `__ to learn how you +can contribute translations of BeeWare documentation. Build a real application! -------------------------- @@ -80,13 +91,12 @@ to proceed, contact the project maintainers on collaborating, especially with new contributors, and will gladly answer any questions or walk you through any problems you may encounter. - - - --- gutter: All Contributions Welcome ----------------------------------- +-------------------------- -But it's not just about code. A successful software project requires documentation, design skills, feedback and bug reports. The BeeWare community acknowledges that all contributions are important - not just the ones that come as a pull request on GitHub. +It's not just about code. A successful software project requires documentation, design +skills, feedback and bug reports. The BeeWare community acknowledges that all +contributions are important - not just the ones that come as a pull request on GitHub. diff --git a/content/contributing/how/dco/contents+es.lr b/content/contributing/how/dco/contents+es.lr deleted file mode 100644 index eecee0e8fa..0000000000 --- a/content/contributing/how/dco/contents+es.lr +++ /dev/null @@ -1,9 +0,0 @@ -_model: page ---- -title: Guía de `DCO` para principiantes ---- -hide_from_index: yes ---- -body: El proyecto BeeWare utiliza un mecanismo conocido como Certificado de Origen de Desarrollador (*Developer Certificate of Origin* por sus siglas en inglés `DCO `__ para gestionar el proceso de asegurar que estamos legalmente autorizados a distribuir todo el código y los activos para el proyecto. Una declaración jurídicamente vinculante que afirma que usted es el creador de su contribución y que desea permitir que BeeWare utilice su trabajo. ---- -summary: Porque a veces los abogados necesitan involucrarse ... diff --git a/content/contributing/how/dco/contents.lr b/content/contributing/how/dco/contents.lr deleted file mode 100644 index 767822cf28..0000000000 --- a/content/contributing/how/dco/contents.lr +++ /dev/null @@ -1,9 +0,0 @@ -_model: page ---- -title: Beginners guide to DCOs ---- -hide_from_index: yes ---- -body: The BeeWare project uses a mechansim known as a `Developer Certificate of Origin (DCO) `__ to manage the process of ensuring that we are legally allowed to distribute all the code and assets for the project. A DCO is a legally binding statement that asserts that you are the creator of your contribution, and that you wish to allow BeeWare to use your work. ---- -summary: Because sometimes lawyers need to get involved... diff --git a/content/contributing/how/dco/copyright/contents+es.lr b/content/contributing/how/dco/copyright/contents+es.lr deleted file mode 100644 index 2f3608d017..0000000000 --- a/content/contributing/how/dco/copyright/contents+es.lr +++ /dev/null @@ -1,63 +0,0 @@ -_model: page ---- -title: Sobre los derechos de autor ---- -body: - -El derecho de autor es el derecho, creado en la ley, que otorga al creador de una obra original los derechos exclusivos para decidir cómo se utiliza y distribuye esa obra. - -El derecho de autor se concede, de forma inmediata y por defecto, a la persona que crea una pieza de trabajo, cuando la crean. Si escribes una canción, escribes un libro o escribes algún software, eres el creador de ese trabajo. Y tienes el derecho de decidir cómo se usará esa creación. - -¿Qué es un copyright? ----------------------------- - -Un copyright - usando la palabra como sustantivo - es propiedad. Es propiedad intelectual. Es algo que se puede comprar y vender. Sólo puede ser propiedad de una sola entidad legal en un momento dado. Si tengo un derecho de autor, y te lo vendo, ahora *tu* tienes los derechos de autor de la obra. - -El derecho de autor no se concede indefinidamente. Se concede por un período de tiempo. En teoría, finalmente expira, y cuando lo hace, la obra vuelve al dominio público. Yo digo en teoría, porque las duraciones de los derechos de autor continúan extendiéndose - pero en teoría, todo trabajo finalmente revertirá al dominio público. - -Si tienes una pieza tangible, física de la propiedad, hay limitaciones obvias en el uso. Éste es mi teléfono. Y si lo tomas sin mi permiso, lo estás robando, y eso es un acto criminal. Pero puedo darte permiso - puedo darte licencia para usar mi teléfono - y entonces que uses mi teléfono no es un acto criminal . - -Dar licencia para usar mi teléfono generalmente no va acompañado de un papeleo legal. Generalmente. Pero podría ser. Si estuviera particularmente preocupado por, digamos, que alguien haga un tweet mientras tenías acceso a mi teléfono, podría hacer que firmaras un acuerdo legalmente vinculante que dice que no harás eso. - -Si decido licenciarte mi teléfono, eso no te da intrínsecamente los derechos de propiedad sobre mi teléfono. Tu no obtienes el derecho de prestar el teléfono a otra persona - a menos que la licencia otorgue ese derecho. Todavía es de *mi* propiedad; solo lo utilizas *bajo licencia*. - -Sin embargo, puedo *darte* o *venderte* mi teléfono - puedo transferirte mi derecho de propiedad. Pero hace una gran diferencia legal si estoy *dándote* mi teléfono, o *licenciándote* el uso de mi teléfono. - -Con suerte, está claro que los términos "copyright" y "license" no son intercambiables - son piezas complementarias del mismo rompecabezas. - -Un pedazo de software es propiedad intelectual. El copyright de una pieza de software es propiedad de alguien - por defecto, el creador. Si deseas utilizar una pieza de software, tienes que ser dado la propiedad - dado el derecho de autor - o concederte una licencia para utilizar el trabajo. Y hace una gran diferencia cuál consigas. - -Copyleft ------------- -Tradicionalmente, se otorgó el derecho de autor para dar a un creador la exclusividad de vender copias de su trabajo. La expectativa era que la gente licenciara copias de su trabajo a cambio de pago. - -Pero a principios de los años 80, la Fundación de Software Libre diseñó un hack legal muy inteligente. Ellos escribieron una licencia de software que, en lugar de defender los derechos del creador, defendían los derechos del receptor. - -El resultado fue copyleft. Copyleft *no* es un sustituto de los derechos de autor. Es un hack legal muy inteligente que *usa* la ley de copyright para hacer cumplir exactamente lo opuesto a lo que el copyright provee. Sin derechos de autor, copyleft no podría existir. - -¿Por qué se requiere una licencia? ------------------------------------------ - -Si *no* proporcionas una licencia, los términos de la licencia predeterminados en su creación son "TODOS LOS DERECHOS RESERVADOS" - incluso si no se dice. Esto significa que nadie puede legalmente utilizar tu código. Y si ves código sin licencia claramente establecida, no puedes usar ese código legalmente. - -Esto aplica a cualquier creación, no importa cuán grande o pequeña - cada mejora/contribución que envías a un proyecto para la inclusión es un trabajo creativo; y eso significa que se requiere una licencia. - -Dominio publico ---------------------- - -Esto probablemente suena como más problemas de lo que se requiere. ¿Por qué no se puede simplemente decir "Bueno, estoy dando esto a la dominio público". - -Como creador de una obra, en algunas jurisdicciones, ciertos derechos *no* pueden ser transferidos. - -Las cuestiones de derecho de autor están estrechamente asociadas con un concepto conocido como Derechos Morales - derechos que se consideran innatos a la experiencia humana. El problema es que el área de los derechos morales es *muy* dependiente de la jurisdicción. Los derechos morales reconocidos por los tribunales europeos -y en particular por los alemanes- son mucho más fuertes que los derechos morales reconocidos por los tribunales de los Estados Unidos de América. - -Por lo tanto, una declaración de que has publicado tu código en el dominio público es en realidad *ilegal* en Alemania. Los tribunales alemanes no reconocerán esa transferencia de propiedad - como tampoco reconocerían un acuerdo legal para vender a sí mismos en la esclavitud. Tu derecho moral a una compensación justa por tu esfuerzo creativo es un derecho moral que se considera inalienable. Y así, tu trabajo vuelve a tener una licencia por defecto: Todos los derechos reservados. Así que los alemanes no pueden usar tu código. - -Certificados de origen del desarrollador --------------------------------------------------- - -Hay varias maneras de administrar el proceso de licencias de contribuciones, pero el proyecto BeeWare utiliza un mecanismo conocido como `Certificados de origen del desarrollador -DCO (por sus siglas en inglés) `__. Para más detalles sobre lo que es el DCO, y lo que significa, `puedes ver nuestra guía explicativa `__. Si necesitas ayuda para configurar tu sistema para cumplir con nuestro DCO `tenemos algunas instrucciones paso a paso para ayudarle a realizarlo `__. ---- -sort_key: 1 ---- -_slug: derechos-de-autor diff --git a/content/contributing/how/dco/copyright/contents.lr b/content/contributing/how/dco/copyright/contents.lr deleted file mode 100644 index 13b184b2cd..0000000000 --- a/content/contributing/how/dco/copyright/contents.lr +++ /dev/null @@ -1,63 +0,0 @@ -_model: page ---- -title: A copyright primer ---- -body: - - -Copyright is the right, created in law, granting a creator of an original work the exclusive rights to decide how that work is used and distributed. - -Copyright is granted, immediately and by default, to the person that creates a piece of work, when they create it. If you write a song, write a book, or write some software - you are the creator of that work. And you have the right to decide how that creation will be used. - -What is a copyright? ---------------------- - -A copyright - using the word as a noun - is property. It's intellectual property. It's something that can be bought and sold. It can only be owned by a single legal entity at any given time. If I have a copyright, and I sell it to you, you now own it. *You* have the copyright for the work. - -Copyright is not granted indefinitely. It's granted for a period of time. In theory, it eventually expires, and when it does, the work reverts to the public domain. I say in theory, because copyright durations keep being extended - but in theory, all work will eventually revert to the public domain. - -If you've got a tangible, physical piece of property, there are obvious limitations on use. This is *my* phone. And if you take it without my permission, you're stealing it, and that's a criminal act. But I can give you permission - I can give you license to use my phone - and then it isn't a criminal act for you to use my phone. - -Giving you license to use my phone usually won't be accompanied by legal paperwork. Usually. But it could be. If I was particularly worried about, say, you tweeting "pooping" while you had access to my phone, I could get you to sign a legally binding agreement that says you won't do that. - -If I do decide to license my phone to you - that doesn't inherently give you property rights over the phone. You don't get the right to lend the phone to someone else -- unless the license grants you that right. It's still *my* property; you're just *using it under license*. - -However, I can *give* or *sell* you my phone - I can transfer my property right to you. But it makes a big legal difference whether I'm *giving* you my phone, or *licensing* you my phone. - -Hopefully, it's clear that the terms "copyright" and "license" aren't interchangable - they're complementary pieces of the same puzzle. - -A piece of software is intellectual property. The copyright for a piece of software is owned by someone - by default, the creator. If you want to use a piece of software, you have to be either given ownership - given the copyright - or granted a license to use the work. And it makes a big difference which one you get. - -Copyleft ----------- -Traditionally, copyright was granted to give a creator exclusivity to sell copies of their work. The expectation was that people would license copies of their work in exchange for payment. - -But in the early 80s, the Free Software Foundation engineered a very clever legal hack. They wrote a software license that, rather than defending the rights of the creator, they defended the rights of the recipient. - -The result was copyleft. Copyleft is *not* a replacement for copyright. It's a very clever legal hack that *uses* copyright law to enforce the exact opposite to what copyright was intended to provide. Without copyright law, copyleft couldn't exist. - -Why is a license required? ----------------------------- - -If you *don't* provide a license, the default licensing terms on your creation are "ALL RIGHTS RESERVED" - even if you don't say that. This means nobody can legally use your code. And if you see code with no clearly offered license, you cannot legally use it. - -This applies to any creation, no matter how big or small - every patch you submit to a project for inclusion is a creative work; and that means a license is required. - -Public Domain --------------- - -This probably sounds like a whole lot more trouble than it's worth. Why can't you just say "Well, I'm giving this away to the public domain". - -As the creator of a work, in some jurisdictions, certain rights *cannot* be transferred. - -Issues of copyright are closely associated with a concept known as Moral Rights - rights that are considered innate to the human experience. The problem is that the area of Moral rights is *very* jurisdiction dependent. Moral rights recognized by European - and, in particular, German courts - are *much* stronger than the moral rights recognized by US courts. - -So - a declaration that you've released your code into the public domain is actually *illegal* in Germany. German courts won't recognize that transfer of ownership - any more than they'd recognize a legal agreement to sell yourself into slavery. Your moral right to fair compensation for your creative effort is a moral right that is considered unalienable. And so, your work reverts to it's default license: All rights reserved. So Germans then can't use your code. - -Developer Certificates of Origin ---------------------------------- - -There are a number of ways to manage the process of licensing contributions, but the BeeWare project uses a mechanism known as a `Developer Certificate of Origin `__. For more details on what DCO is, and what it means, `see our explanatory guide `__. If you've need help configuring your system to comply with our DCO `we've got some step by step instructions to help you out `__. - ---- -sort_key: 1 diff --git a/content/contributing/how/dco/how/contents+es.lr b/content/contributing/how/dco/how/contents+es.lr deleted file mode 100644 index 9253b24a23..0000000000 --- a/content/contributing/how/dco/how/contents+es.lr +++ /dev/null @@ -1,21 +0,0 @@ -_model: page ---- -title: ¿Cómo firmar un 'DCO'? ---- -sort_key: 3 ---- -body: - -Para indicar que acepta los términos del Certificado de Origen de Desarrollador (por sus siglas en inglés DCO), simplemente agregue una línea a cada mensaje de envío de git: - -.. code-block:: - - Firmado por: Joe Smith - -Si configura su `user.name` y `user.email` como parte de su configuración git, puede firmar su commit automáticamente con `git commit -s`. ---- -summary: ---- -incomplete: yes ---- -_slug: como-firmar diff --git a/content/contributing/how/dco/how/contents.lr b/content/contributing/how/dco/how/contents.lr deleted file mode 100644 index 53784501b9..0000000000 --- a/content/contributing/how/dco/how/contents.lr +++ /dev/null @@ -1,17 +0,0 @@ -_model: page ---- -title: How to sign a DCO ---- -sort_key: 3 ---- -body: - -To indicate that you agree to the terms of the DCO, you just add a line to every git commit message:: - - Signed-off-by: Joe Smith - -If you set your user.name and user.email as part of your git configuration, you can sign your commit automatically with `git commit -s`. ---- -summary: ---- -incomplete: yes diff --git a/content/contributing/how/dco/what/contents+es.lr b/content/contributing/how/dco/what/contents+es.lr deleted file mode 100644 index 304b9a17d9..0000000000 --- a/content/contributing/how/dco/what/contents+es.lr +++ /dev/null @@ -1,59 +0,0 @@ -_model: page ---- -title: ¿Qué es un DCO? ---- -body: - -El proyecto BeeWare utiliza un mecanimo conocido como `Certificado de origen del Desarrollador - DCO (por sus siglas en inglés) `__ para administrar este proceso. El DCO es una declaración jurídicamente vinculante que afirma que usted es el creador de su contribución y que desea permitir que BeeWare utilice su trabajo. - -El acuso de recibo de este permiso se realiza mediante un proceso de inicio de sesión en Git. El *sign-off* es una línea simple al final de la explicación para el parche. El texto del DCO es bastante simple (de `developercertificate.org `__):: - - Certificado de origen del desarrollador - Versión 1.1 - - Copyright (C) 2004, 2006 La Fundación Linux y sus colaboradores. - 660 York Street, Suite 102, - San Francisco, CA 94110 USA - - Todo el mundo está autorizado a copiar y distribuir copias - documento de licencia, pero no se permite cambiarlo. - - Certificado de origen del desarrollador 1.1 - - Al hacer una contribución a este proyecto, certifico que: - - (a) La contribución fue creada total o parcialmente por mí y yo - tienen derecho a presentarlo bajo la licencia de código abierto - indicada en el expediente; o - - (b) La contribución se basa en trabajos anteriores que, a la mejor - de mi conocimiento, está cubierto bajo una fuente abierta apropiada - licencia y tengo el derecho bajo esa licencia de presentar - trabajo con modificaciones, ya sean creadas en su totalidad o en parte - por mí, bajo la misma licencia de código abierto (a menos que sea - autorizada a presentar una licencia diferente), según se indica - en el archivo; o - - (c) La contribución me fue proporcionada directamente por algún otro - persona que certificó (a), (b) o (c) y no he modificado - eso. - - (d) Entiendo y estoy de acuerdo en que este proyecto y la contribución - pública y que el registro de la contribución (incluida toda la - información personal que envío con ella, e incluyendo mi firma) se - mantiene indefinidamente y puede ser redistribuida - con este proyecto o las licencias de código abierto involucradas. - -Si está dispuesto a aceptar estos términos, simplemente añada una línea a cada mensaje de envío de git:: - - Firmado por: Joe Smith - -Si configura su ``user.name`` y ``user.email`` como parte de su configuración de git, puede firmar su commit automáticamente con ``git commit -s``. - -Por desgracia, usted tiene que usar su nombre real (es decir, pseudónimos o contribuciones anónimas no se pueden hacer). Esto se debe a que el DCO es un documento jurídicamente vinculante, otorgando al proyecto BeeWare el uso de su trabajo. ---- -sort_key: 2 ---- -incomplete: yes ---- -_slug: que-es diff --git a/content/contributing/how/dco/what/contents.lr b/content/contributing/how/dco/what/contents.lr deleted file mode 100644 index 8c2ee47935..0000000000 --- a/content/contributing/how/dco/what/contents.lr +++ /dev/null @@ -1,59 +0,0 @@ -_model: page ---- -title: What is a DCO? ---- -body: - - -The BeeWare project uses a mechanism known as a `Developer Certificate of Origin (DCO) `__ to manage this process. The DCO is a legally binding statement that asserts that you are the creator of your contribution, and that you wish to allow BeeWare to use your work. - -Acknowledgement of this permission is done using a sign-off process in Git. The sign-off is a simple line at the end of the explanation for the patch. The text of the DCO is fairly simple (from `developercertificate.org `__):: - - Developer Certificate of Origin - Version 1.1 - - Copyright (C) 2004, 2006 The Linux Foundation and its contributors. - 660 York Street, Suite 102, - San Francisco, CA 94110 USA - - Everyone is permitted to copy and distribute verbatim copies of this - license document, but changing it is not allowed. - - Developer's Certificate of Origin 1.1 - - By making a contribution to this project, I certify that: - - (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - - (b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - - (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. - -If you are willing to agree to these terms, you just add a line to every git commit message:: - - Signed-off-by: Joe Smith - -If you set your ``user.name`` and ``user.email`` as part of your git configuration, you can sign your commit automatically with ``git commit -s``. - -Unfortunately, you have to use your real name (i.e., pseudonyms or anonymous contributions cannot be made). This is because the DCO is a legally binding document, granting the BeeWare project to use your work. - ---- -sort_key: 2 ---- -incomplete: yes diff --git a/content/contributing/how/first-time/github-notifications-101/contents.lr b/content/contributing/how/first-time/github-notifications-101/contents.lr index ec7f9ea525..3cc527748c 100644 --- a/content/contributing/how/first-time/github-notifications-101/contents.lr +++ b/content/contributing/how/first-time/github-notifications-101/contents.lr @@ -1,13 +1,17 @@ _model: page --- +sort_key: 4 +--- title: GitHub Notifications 101 --- +summary: So you're now using GitHub, and it's notifying you. What now? +--- body: Once you start contributing to BeeWare, GitHub is going to start notifying you about things. -This is a good thing! But it can get overwhelming, so here are some tips to +This is a good thing! But it can get overwhelming; so, here are some tips to help you battle the deluge. - If you prefer email notifications only, disable the "Web" notifications. @@ -33,7 +37,7 @@ Each repo has a number of notification settings: - Ignoring - never ever ever be notified. You can check what repos you're watching across all of GitHub from the -`watching page `_ +`watching page `_. Email filters @@ -58,21 +62,18 @@ If you're only subscribed to a repo: - the email will be cc'd to ``subscribed@noreply.github.com`` - Ssshhhhhh ~~~~~~~~~~~ -If you want to mute a specific thread, you can click the 'Unsubscribe' button on any issue or pull request. +If you want to mute a specific thread, you can click the 'Unsubscribe' button +on any issue or pull request. + +If you get email, you can click on the 'Mute this thread'. -If you get email, you can click on the 'Mute this thread' --- gutter: GitHub has a bunch of resources to help you out with notifications. -- `About Notifications `_ -- `Managing Notifications `_ ---- -summary: So you're now using GitHub, and it's notifying you. What now? ---- -sort_key: 4 +- `About Notifications `_ +- `Managing Notifications `_ diff --git a/content/contributing/how/first-time/github/contents.lr b/content/contributing/how/first-time/github/contents.lr index 6928741a71..f0b782f5fa 100644 --- a/content/contributing/how/first-time/github/contents.lr +++ b/content/contributing/how/first-time/github/contents.lr @@ -1,17 +1,20 @@ _model: page --- +sort_key: 3 +--- title: Using GitHub --- +summary: How to submit a pull request using GitHub +--- body: -This GitHub tutorial is lovingly based on the -`DjangoGirls How To Contribute Tutorial `__ which -is available under a Creative Commons Attribution-ShareAlike 4.0 -license. +This GitHub tutorial is lovingly based on the `DjangoGirls How To Contribute +Tutorial `__ which is available under +a Creative Commons Attribution-ShareAlike 4.0 license. -For this tutorial, we will be using the -`Briefcase `__ repository as a basis for the -links and references +For this tutorial, we will be using the `Briefcase +`__ repository as a basis for the links +and references. Getting started and prerequisites ---------------------------------- @@ -20,15 +23,15 @@ For contributing to BeeWare, the following is needed to get started: - a `GitHub account `__ - in the case of complex edits familiarity with `Git command line - basics `__ or - familiarity with an app (`Windows and Mac `__) to push your edits made on your - computer to GitHub. + basics `__ or + familiarity with an app (`Windows and Mac `__) + to push your edits made on your computer to GitHub. Fork the repository ---------------------------------- -First fork the `Briefcase `__ repository to your -personal GitHub account: +First, fork the `Briefcase `__ repository +to your personal GitHub account: |Fork button| @@ -38,8 +41,7 @@ Editing Documentation Simple changes ---------------------------------- -For simple changes like typo corrections you can use the GitHub online -editor: +For simple changes like typo corrections you can use the GitHub online editor: - Open your local fork page on GitHub, - go to *README.rst* file in any chapter, @@ -49,8 +51,7 @@ and you can edit the chapter directly on github.com. |Edit button| -RST syntax is used to edit the individual pages of the -documentation. +RST syntax is used to edit the individual pages of the documentation. |GitHub editor| @@ -64,13 +65,12 @@ Save your changes and create a pull request as explained below. New code and complex changes ---------------------------------- -For adding new code, extending classes, or complex changes, you need to -get a copy of the code to your local computer. +For adding new code, extending classes, or complex changes, you need to get a +copy of the code to your local computer. Either use the GitHub app for your operating system (mentioned above) or -``git`` command line to get the repository locally. You get the -repository address from the front page of your own GitHub repository -fork: +``git`` command line to get the repository locally. You get the repository +address from the front page of your own GitHub repository fork: :: @@ -119,19 +119,18 @@ Example: Making a pull request ---------------------------------- -After you have finished your changes you need to create `a pull -request `__ on -GitHub. BeeWare will get notified about the pull request, review your -changes, suggest any corrections if needed and then *pull* your changes -to the main version. +After you have finished your changes you need to create `a pull request +`__ on GitHub. BeeWare +will get notified about the pull request, review your changes, suggest any +corrections if needed and then *pull* your changes to the main version. In your own repository on GitHub press do *Compare & pull request* |image4| -Fill in the information *why* this change is being made. The reviewer -can see the details of the actual change, so you don't need repeat the -content of the change. +Fill in the information *why* this change is being made. The reviewer can see +the details of the actual change, so you don't need repeat the content of the +change. Then press *Create pull request*. @@ -139,8 +138,6 @@ GitHub emails will notify you for the follow up process. --------------- - - .. |Fork button| image:: /contributing/how/first-time/github/fork.png :class: img-fluid @@ -153,10 +150,6 @@ GitHub emails will notify you for the follow up process. .. |image4| image:: /contributing/how/first-time/github/pull_request.png :class: img-fluid ---- -summary: How to submit a pull request using GitHub ---- -sort_key: 3 --- gutter: @@ -167,5 +160,4 @@ There are many useful resources to help you learn how to log issues and raise Pull Requests in GitHub: * `Contributing to Open Source `__ - * `How to Fork a Repo `__ - + * `How to Fork a Repo `__ diff --git a/content/contributing/how/first-time/imposter-syndrome/contents.lr b/content/contributing/how/first-time/imposter-syndrome/contents.lr index a112bcdbd5..19c9639b1a 100644 --- a/content/contributing/how/first-time/imposter-syndrome/contents.lr +++ b/content/contributing/how/first-time/imposter-syndrome/contents.lr @@ -1,35 +1,64 @@ _model: page --- +sort_key: 1 +--- title: Imposter Syndrome --- +summary: Don't think you're ready to be an open source contributor? You're wrong. +--- body: +There may be a little voice inside your head that is telling you that you're +not ready; that you need to do one more tutorial; that you aren't ready to be +an open source contributor. After all, you're just a beginner. What could you +possibly offer a project like BeeWare? -There may be a little voice inside your head that is telling you that you're not ready; that you need to do one more tutorial; that you aren't ready to be an open source contributor. After all, you're just a beginner. What could you possibly offer a project like BeeWare? - -I assure you - the little voice in your head is wrong. If you can write code at all, you can contribute code to open source, and to BeeWare. +I assure you - the little voice in your head is wrong. If you can write code at +all, you can contribute code to open source, and to BeeWare. -You're not the first person to have those thoughts, either. Even the members of the core team of this project have these thoughts from time to time. It's called "imposter syndrome", and it's a really common problem. The good news is - we're here to help you get over it. +You're not the first person to have those thoughts, either. Even the members of +the core team of this project have these thoughts from time to time. It's +called "imposter syndrome", and it's a really common problem. The good news is +- we're here to help you get over it. -This tutorial exists to make sure you know exactly what process you have to follow in order to get your patch merged. In addition to these procedural instructions, this project has a Code of Conduct. This Code of Conduct is there to give you confidence that no matter what mistakes you make, you'll be treated with respect. Everyone makes mistakes - that's a natural part of learning. Our pledge to you is that we are here to help you learn, not to insult or belittle you for learning. +This tutorial exists to make sure you know exactly what process you have to +follow in order to get your patch merged. In addition to these procedural +instructions, this project has a Code of Conduct. This Code of Conduct is there +to give you confidence that no matter what mistakes you make, you'll be treated +with respect. Everyone makes mistakes - that's a natural part of learning. Our +pledge to you is that we are here to help you learn, not to insult or belittle +you for learning. -Being an open source contributor doesn't just mean writing code, either. You can help out by writing documentation, tests, or even giving feedback about the project (and yes - that includes giving feedback about the contribution process). Some of these contributions may be the most valuable to the project as a whole, because you're coming to the project with fresh eyes, so you can see the errors and assumptions that seasoned contributors have glossed over. +Being an open source contributor doesn't just mean writing code, either. You +can help out by writing documentation, tests, or even giving feedback about the +project (and yes - that includes giving feedback about the contribution +process). Some of these contributions may be the most valuable to the project +as a whole, because you're coming to the project with fresh eyes, so you can +see the errors and assumptions that seasoned contributors have glossed over. -You can't do any damage, either - either to your own computer, or to the project as a whole. BeeWare projects don't touch any part of your computer or operating system that could do any serious damage. Worst case, you'll end up with a couple of extra files on your hard drive, which can be easily deleted afterwards. And every contribution you submit to BeeWare is reviewed before it is integrated into the "official" project, and you'll get feedback to help you correct any problems that may exist. +You can't do any damage, either - either to your own computer, or to the +project as a whole. BeeWare projects don't touch any part of your computer or +operating system that could do any serious damage. Worst case, you'll end up +with a couple of extra files on your hard drive, which can be easily deleted +afterwards. And every contribution you submit to BeeWare is reviewed before it +is integrated into the "official" project, and you'll get feedback to help you +correct any problems that may exist. -So - don't be afraid to contribute. If you've gotten this far, you've demonstrated you have an interest in contributing - and that's all you need. We can help you the rest of the way. +So - don't be afraid to contribute. If you've gotten this far, you've +demonstrated you have an interest in contributing - and that's all you need. We +can help you the rest of the way. -Now it's time to roll up your sleeves, and `pick a project where you can contribute`_. +Now it's time to roll up your sleeves, and `pick a project where you can +contribute`_. .. _pick a project where you can contribute: /contributing/how/first-time/what/ ---- -sort_key: 1 ---- -summary: Don't think you're ready to be an open source contributor? You're wrong. + --- gutter: Connecting with Confident Authenticity ---------------------------------------------- -Learn more about how to combat imposter syndrome: watch `"Bake the Cookies, Wear the Dress" `__ by Adrienne Lowe +Learn more about how to combat imposter syndrome: watch `"Bake the Cookies, +Wear the Dress" `__ by Adrienne +Lowe diff --git a/content/contributing/how/first-time/setting-up-your-environment/contents.lr b/content/contributing/how/first-time/setting-up-your-environment/contents.lr index 940da95307..ed2ade2909 100644 --- a/content/contributing/how/first-time/setting-up-your-environment/contents.lr +++ b/content/contributing/how/first-time/setting-up-your-environment/contents.lr @@ -1,108 +1,130 @@ _model: page --- +sort_key: 4 +--- title: Setting up your environment --- +summary: How to get your system setup to contribute +--- _slug: setup --- body: -In order to get contributing, you're going to need to setup a -**development environment** - a place where you can work on code where it can -behave the same as everyone else's environment. +In order to get contributing, you're going to need to setup a +**development environment** - a place where you can work on code where it can +behave the same as everyone else's environment. -Many parts of BeeWare use the same tools: a specific version of Python, and -virtual environment controls. +Many parts of BeeWare use the same tools: a specific version of Python, and +virtual environment controls. Python ------------ +------- -Python is a scripting language, which is available on a number of different -operating systems. However, depending on what system you are using, your -version of Python is going -to be different. Because of this reason, we specify exactly what version of Python -we expect the code to work with. +Python is a scripting language, which is available on a number of different +operating systems. However, depending on what system you are using, your +version of Python is going to be different. Because of this reason, we specify +exactly which version of Python we expect the code to work with. For the following instructions, we're going to assume that you know exactly -which version of Python you need to install. Normally this is listed in the -README.md file or in the tutorial information. Our `CI -`_ systems have to be told exactly what -version of Python is required, too. So if you're really stuck, try looking at -the :code:`.travis.yml` or :code:`circle.yml` file for the specific version you -need. +which version of Python you need to install. Normally, this is listed in the +``README.md`` file or in the tutorial information. Our `CI +`_ systems have to be told exactly +which version of Python is required, too. So if you're really stuck, try +looking at the :code:`.github/workflows/ci.yml` file for the specific version +you need. pyenv ~~~~~~ -`pyenv `_ is a way to get multiple versions of -Python working on your machine at the same time. It allows you to pick and choose whichever -version you need for a particular project. +`pyenv `_ is one way to get multiple versions of +Python working on your machine at the same time. It allows you to pick and choose +whichever version you need for a particular project. - * MacOSX - You can install pyenv via `brew `_, by running :code:`brew install pyenv` - * Other - use the `automatic installer `_. + * MacOSX - You can install pyenv via `brew + `_, by running + :code:`brew install pyenv` + * Other - use the `automatic installer `_ Once :code:`pyenv` is installed, you need to install the specific Python version. This information is stored in a :code:`.python-version` file, which means you can have different versions of Python used in different projects on -your computer. +your computer. -To install and set the Python version: +To install and set the Python version: .. code-block:: bash $ cd /path/to/your/project - $ pyenv install 3.5.1 - $ pyenv local 3.5.1 + $ pyenv install 3.12.1 + $ pyenv local 3.12.1 + +More information about pyenv is available on `their website +`_. -More information about pyenv is available on `their website `_ +Virtual Environments +--------------------- -virtualenv ------------ +When Python is installed, it provides a single global environment. By default, if you +install a package, it will be installed into this global environment. -Once Python is installed, you're going to want to be able to install different -Python packages. Since you may have more than one project being worked on, and -more than one version of Python, having a way to make sure that only specific -Python packages are available at any one time is handy. +However, if you're working on more than one Python project, it's entirely likely that +those multiple projects will have different - and in some cases, conflicting - +requirements. What you need is a way to isolate each project so that installing a +package for one project won't force that same package to be installed for the second +project. -One way we can do this is via `virtualenv `_. +This is done using *Virtual Environments*. A Virtual Environment, or ``venv``, is an +isolated environment that can be easily created, destroyed or recreated. Any package +installed in the virtual environment is only accessible *inside* that virtual +environment. Virtual environments are sometimes referred to as a "sandbox" - a safe +place to play, where if you make a mistake, you can knock down everything you've built +and start again. -Using `pip `_, we can install virtualenv +Python provides the ``venv`` module to create new virtual environments. Each virtual +environment has a name that can be used to identify the environment. To create a fresh +virtual environment named "my-venv", run: .. code-block:: bash - - $ pip install virtualenv -Then, we want to setup a virtualenv that we can then activate. Having more than -one virtualenv is ok, but only one can be activated at a time. Make sure you -have your Python selection done with :code:`pyenv`, so that we know what -version of Python to use + $ python -m venv my-venv + +The version of Python that you use to create the virtual environment will be the version +that is used by default *inside* the virtual environment. If you've got multiple Python +versions installed, or you're using a tool like ``pyenv`` to manage Python versions, +ensure that the Python version that is currently active (or the version you reference +when invoking the ``-m venv`` command) is the version you intend. Once a virtual +environment has been created, you can't change the Python version that it is using. To +change the Python version, you need to create a fresh virtual environment. +Invoking ``-m venv`` will *create* the virtual environment, but the environment is not +yet *active*. The virtual environment is a collection of files on disk, stored in a +directory that matches the name of the environment. To activate the virtual environment, +you run one of the files generated as part of the environment: .. code-block:: bash - - $ virtualenv -p $(pyenv which python) env -Then, we can activate the virtual environment. + $ source my-venv/bin/activate +This will result in a prefix being added to your command line prompt letting you know +you're in a virtual environment: .. code-block:: bash - - $ source env/bin/activate -This will result in a little note in your command line letting you know you're -in a virtual environment + (my-venv) $ -.. code-block:: bash - - (env) $ +While the virtual environment is active, any ``pip install`` command will *only* affect +the virtual environment. It doesn't matter if you change directories - if your prompt +has a prefix, that virtual environment is active. + +If you open a second terminal window, the environment will *not* be active - you need to +re-activate the environment in every terminal session where you want to use the +environment. If you get errors about libraries not being available that you're *certain* +you've installed - check whether your virtual environment is active. -To disable your virtualenv: +To deactivate the virtual environment, run: .. code-block:: bash - - $ deactivate + (my-venv) $ deactivate ---- -summary: How to get your system setup to contribute ---- -sort_key: 4 +Once deactivated, the prefix will be dropped from the prompt. diff --git a/content/contributing/how/first-time/what-is-a/ci/contents.lr b/content/contributing/how/first-time/what-is-a/ci/contents.lr index 635c79f17c..c9acb0dd17 100644 --- a/content/contributing/how/first-time/what-is-a/ci/contents.lr +++ b/content/contributing/how/first-time/what-is-a/ci/contents.lr @@ -2,23 +2,24 @@ _model: page --- title: CI --- +summary: What is CI, or Continuous Integration +--- body: -Continuous integration, or CI, is a way that we can test code continuously. -These systems will automatically listen for new Pull Requests and other events, -and automatically run test suites, and other automatic processes. +Continuous integration, or CI, is a way that we can test every code change that is made +to a project. These systems automatically listen for new pull requests and other events, +and automatically run test suites, and other automatic processes. + +We use GitHub's CI system: `Actions `_. Normally +the *build status* of a project is displayed as an image on the project's README file. +Green means the tests have been successful, and red means they have not. Clicking the +image will show you the results of these tests. -We use a number of different CI systems: `Travis CI `_ -and `BeeKeeper `_ . Normally the *build status* of a -project is displayed as an image on the project's README file. Green means the -tests have been successful, and red means they have not. Clicking the image -will show you the results of these tests. --- gutter: Unsure which CI environment is being used? --------------------------------------------------------- +------------------------------------------- -Check for the configuration file. `.travis.yml` is Travis, `beekeeper.yml` is BeeKeeper. ---- -summary: What is CI, or Continuous Integration +Check for the configuration file. GitHub CI workflows are configured in the +``.github/workflows`` directory. diff --git a/content/contributing/how/first-time/what-is-a/package-manager/contents.lr b/content/contributing/how/first-time/what-is-a/package-manager/contents.lr index f0f0ec6aa6..43894bf075 100644 --- a/content/contributing/how/first-time/what-is-a/package-manager/contents.lr +++ b/content/contributing/how/first-time/what-is-a/package-manager/contents.lr @@ -2,42 +2,36 @@ _model: page --- title: Package Managers --- +summary: How you can manage your installed packages +--- body: Installing software on your computer can be interesting. Sometimes you have to download a file and then install it yourself, or copy files to specific places -on your computer. +on your computer. -However, `package managers` help make this process easier by allowing for the -automation of installation of software. +However, package managers help make this process easier by allowing for the +automation of installation of software. There are different levels of package managers: for the operating system level, -as well as one specifically for Python packages. - +as well as one specifically for Python packages. MacOSX ---------------- +------- `Homebrew `_ is the standard for installing software on your -Mac. This is the system that's used if you run a :code:`brew install` command. +Mac. This is the system that's used if you run a :code:`brew install` command. Linux ------------- +------ Depending on what family of operating system you run, you'll use -:code:`apt-get` (for Debian and Ubuntu) or :code:`yum` (for Red Hat and CentOS) +:code:`apt-get` (for Debian and Ubuntu) or :code:`yum` (for Red Hat and CentOS). Python ------------ -:code:`pip` is the way you can install Python software. Running :code:`pip -install` uses the `Python Packaging Index `_, -also known as `PyPI` or "The Cheese Shop", it's a central repository for Python -code. Many BeeWare projects can be installed using `pip`. - -Why is it called "The Cheese Shop"? It's a `Monty Python -`_ reference :) ---- -gutter: ---- -summary: How you can manage your installed packages +:code:`pip` is the way you can install Python software. Running :code:`pip install` uses +the `Python Packaging Index `_, also known as "PyPI". PyPI is a +central repository for Python code. Many BeeWare projects can be installed using +:code:`pip`. diff --git a/content/contributing/how/first-time/what/contents+fr.lr b/content/contributing/how/first-time/what/contents+fr.lr index 26f5054c5d..bf1d770cff 100644 --- a/content/contributing/how/first-time/what/contents+fr.lr +++ b/content/contributing/how/first-time/what/contents+fr.lr @@ -9,7 +9,7 @@ est celui qui correspond à vos connaissances, votre expérience, et vos centres d'intérêts. Avant de commencer ------------------ +------------------- Avant de commencer à contribuer, cela peut aider d'avoir un ressenti du projet dans son ensemble. Si vous n'avez pas encore complété le `tutoriel BeeWare @@ -27,7 +27,7 @@ qu'elle l'était !), voici quelques idées d'où vous engager, selon vos compét et vos intérêts. Programmation Python -------------------- +--------------------- Briefcase ~~~~~~~~~ @@ -67,7 +67,7 @@ La documentation de Colosseum a un `guide de contribution vous mener à travers votre première contribution à Colosseum. Programmation avec interface graphique ----------------- +--------------------------------------- Si vous avez de l'expérience avec une bibliothèque de widgets natifs — Cocoa sur macOS, GTK+ sur Linux, Windows Forms, ou les bibliothèques natives iOS ou Android, @@ -143,7 +143,7 @@ rencontrez des problèmes, signalez-les comme des bogues ; si vous êtes témér voyez si vous trouvez comment *résoudre* le bogue. Utilisation pratique ----------------- +--------------------- Un des meilleurs moyens pour nous de déterminer où sont nos lacunes – tant dans la documentation que les APIs – est que des gens utilisent réellement BeeWare pour @@ -169,7 +169,7 @@ summary: Alors vous voulez aider – mais où devriez-vous commencer ? gutter: Première contribution ------------------------- +---------------------- Vous voulez commencer petit ? Une fois que vous aurez commencé à explorer les tutoriels, jetez un œil aux problèmes marqués `[good first issue] diff --git a/content/contributing/how/first-time/what/contents.lr b/content/contributing/how/first-time/what/contents.lr index fee301035e..ccb585ef15 100644 --- a/content/contributing/how/first-time/what/contents.lr +++ b/content/contributing/how/first-time/what/contents.lr @@ -1,7 +1,11 @@ _model: page --- +sort_key: 2 +--- title: What should I do? --- +summary: So you want to help - but where should you start? +--- body: The best place to start with any open source contribution is with something that @@ -159,10 +163,6 @@ app, log issues with the BeeWare projects that caused problems. This will enable us to identify what we need to improve - and, it might even be a source of inspiration for you to contribute! ---- -sort_key: 2 ---- -summary: So you want to help - but where should you start? --- gutter: diff --git a/content/contributing/how/process/contents.lr b/content/contributing/how/process/contents.lr index 763a59c116..c20bb85124 100644 --- a/content/contributing/how/process/contents.lr +++ b/content/contributing/how/process/contents.lr @@ -8,134 +8,134 @@ summary: The BeeWare development process --- body: -Code style ---------------- - -Please follow these coding standards when writing code for inclusion in BeeWare projects. Unless otherwise specified, -follow :pep:`8` (with careful attention paid to -`Section 2 `__) Use -`flake8 `__ to check for problems in this area. Remember that :pep:`8` is only a -guide, so respect the style of the surrounding code as a primary goal. - -An exception to :pep:`8` is our rules on line lengths. Don't limit lines of code to 79 characters if it means the code -looks significantly uglier or is harder to read. We allow up to 119 characters as this is the width of GitHub code -review; anything longer requires horizontal scrolling which makes review more difficult. This check is included when you -run ``flake8``. Documentation, comments, and docstrings should be wrapped at 79 characters, even though :pep:`8` -suggests 72. - -* Use four spaces for indentation. - -* Use four space hanging indentation rather than vertical alignment:: - - raise AttributeError( - 'Here is a multine error message ' - 'shortened for clarity.' - ) - - Instead of:: - - raise AttributeError('Here is a multine error message ' - 'shortened for clarity.') - - This makes better use of space and avoids having to realign strings if the length of the first line changes. - -* Use single quotes for strings, or a double quote if the the string contains a single quote. Don't waste time doing - unrelated refactoring of existing code to conform to this style. - -* Avoid use of "we" in comments, e.g. "Loop over" rather than "We loop over". - -* Use underscores, not camelCase, for variable, function and method names +Overview +--------- -* Use InitialCaps for class names (or for factory functions that return classes). +All changes to code and documentation should be `submitted +`_ via a pull request to the GitHub repository for +the project. -* Use the Google Style Python Docstrings and :pep:`257`, type annotation with :pep:`484` is optional. +Most projects have a dedicated contribution guide with details specific to that project, +or specific types of contribution. This documentation can be found on Read the Docs. For +example, `Briefcase's documentation `__ contains +contribution guides for both `code +`__ and +`documentation +`__. - :: +All submissions should abide by the `BeeWare Code of Conduct +`_. - def function_with_types_in_docstring(param1, param2): - """Example function with types documented in the docstring. +Change Notes +------------- - Args: - param1 (int): The first parameter. - param2 (str): The second parameter. +Several BeeWare projects, notably Briefcase and Toga, require that each pull request is +submitted with a change note. These change notes are compiled together when a new +release is cut for the project, producing the release notes for the new release. - Returns: - bool: The return value. True for success, False otherwise. +BeeWare uses `Towncrier `__ to manage +change notes. - """ - - `More examples of Google Docstrings `__ - -* In test docstrings, state the expected behavior that each test demonstrates. Don't include preambles such as "Tests - that" or "Ensures that". - -* Reserve ticket references for obscure issues where the ticket has additional details that can't be easily described in - docstrings or comments. Include the ticket number at the end of a sentence like this:: - - def test_foo(): - """A test docstring looks like this (#123456). - """ +A change note file should be created in the ``changes`` directory and named +using this format:: -Imports ---------------- + ..rst -Use `isort `_ to automate -import sorting using the guidelines below. +For instance, a pull request that fixes GitHub issue #42 would be named +``42.bugfix.rst``. If a pull request is not associated with a specific issue, then the +pull request number can be used instead. You may need to create the pull request +*without* a change note to get a pull request number allocated, then push an update that +includes the change note with the newly allocated pull request number. -Quick start:: +The change types for the change note should be one of the following: - $ pip install isort - $ isort -rc . +* ``feature`` +* ``bugfix`` +* ``doc`` +* ``removal`` +* ``misc`` -This runs ``isort`` recursively from your current directory, modifying any -files that don't conform to the guidelines. If you need to have imports out -of order (to avoid a circular import, for example) use a comment like this:: +The ``misc`` type is reserved for changes that do not affect users, and don't need to be +noted in the release notes. Minor typographical fixes in documentation, updates to CI +configuration, and bug fixes for features that haven't yet been formally released are +examples of features that would be described using ``misc`` markers. - import module # isort:skip +A change note should be a single line of text, providing a high level summary of the +change from the perspective of the user, not a deep technical description or +implementation detail. It is distinct from a commit message. A commit message describes +what has been done so that future developers can follow the reasoning for a change. A +change note is a "user facing" description, described in terms of the new capability +that is available as a result of change. It may help to think of the change note as a +press release announcing the change, rather than a commit description. -Put imports in these groups: standard library, third-party libraries, other BeeWare components, local BeeWare component, -try/excepts. Sort lines in each group alphabetically by the full module name. Place all ``import module`` statements -before ``from module import objects`` in each section. Use absolute imports for other BeeWare components and relative -imports for local components. +For example, if you fix a bug caused by date handling, the commit message or pull +request description might read: -On each line, alphabetize the items with the upper case items grouped before the lower case items. + Added a MM-DD-YYYY format validator to the DateWidget validation chain. -Break long lines using parentheses and indent continuation lines by 4 spaces. Include a trailing comma after the last -import and put the closing parenthesis on its own line. +This describes the change that was made to the implementation - detail that will be +helpful to the person reviewing the code. However, the corresponding change note might +read something like: -Use a single blank line between the last import and any module level code, and use two blank lines above the first -function or class. + Date widgets can now accept dates in US format. +This describes the functional change as it will be experienced by end users. A user can +read this description without needing to know anything about the implementation. -Miscellaneous ---------------- - -Remove ``import`` statements that are no longer used when you change code. `flake8 `__ will identify these imports for you. If an unused import needs to remain for -backwards-compatibility, mark the end of with ``# NOQA`` to silence the flake8 warning. - -Systematically remove all trailing whitespaces from your code as those add unnecessary bytes, add visual clutter to the -patches and can also occasionally cause unnecessary merge conflicts. Some IDE's can be configured to automatically -remove them and most VCS tools can be set to highlight them in diff outputs. +Code style +----------- + +BeeWare's projects use `Pre-commit `__ to automate +code style adherence. These checks are defined in the +``.pre-commit-config.yaml`` file for each repository and are automatically run in +`CI `_ when a Pull Request is +opened. + +To automate the Pre-commit checks in your local development environment with +each ``git`` commit, run :code:`pre-commit install`. + +Included Pre-commit checks: + +* `Black `__ ensures uniform + code formatting +* `docformatter `__ ensures + uniform formatting for docstrings and comments +* `pyupgrade `__ ensures code is using + the latest best practices for Python +* `isort `__ ensures uniform ``import`` + statements +* `flake8 `__ checks for common coding and + syntax issues +* Misc checks that validate structured documents such as TOML files and remove + unnecessary whitespace + +Additional guidelines: + +* Avoid use of "we" in comments, e.g. "Loop over" rather than "We loop over" +* Use underscores, not camelCase, for variable, function and method names +* Use InitialCaps for class names (or for factory functions that return classes) +* Use Sphinx-style docstrings and :pep:`257`; type annotation with :pep:`484` + is optional but encouraged. -Sign your work ---------------- + For example:: -Before we can merge your contribution into BeeWare, you need to give us permission to do so. Since you're an author of a -creative work (a piece of code, or some documentation), you automatically own the copyright for that work. BeeWare -can't legally use that contribution unless you give us permission to do so. + def function_name(param1: int, param2: str) -> bool: + """Example function with types and a docstring. -The BeeWare project uses a mechanism known as a `Developer Certificate of Origin (DCO) `__ to -manage this process. The DCO is a legally binding statement that asserts that you are the creator of your contribution, -and that you wish to allow BeeWare to use your work. + :param param1: The first parameter. + :param param2: The second parameter. -To indicate that you agree to the terms of the DCO, you just add a line to every git commit message:: + :returns: The return value. True for success, False otherwise. + """ - Signed-off-by: Joe Smith +* In test docstrings, state the expected behavior that each test demonstrates. + Don't include preambles such as "Tests that" or "Ensures that". +* Reserve ticket references for obscure issues where the ticket has additional + details that can't be easily described in docstrings or comments. Include the + ticket number at the end of a sentence like this:: -If you set your ``user.name`` and ``user.email`` as part of your git configuration, you can sign your commit -automatically with ``git commit -s``. + def test_foo(): + """A test docstring looks like this (#123456).""" -If you have more questions about Developer Certificates of Origin, why they are required, what they mean, and how to -configure your system to use them, see `The Beginners Guide to DCOs `__, or `get in touch with -the core team `__. +* Unless otherwise specified, follow :pep:`8` (with careful attention paid to `Section 2 + `__). diff --git a/content/contributing/how/translations/contents+de.lr b/content/contributing/how/translations/contents+de.lr index bf07f2282a..cba6744caa 100644 --- a/content/contributing/how/translations/contents+de.lr +++ b/content/contributing/how/translations/contents+de.lr @@ -9,9 +9,3 @@ Du willst mithelfen, die Inhalte dieser Website zu übersetzen oder zu aktualisi Diese Seiten basieren hauptsächlich auf `Lektor-Dateien (.lr) `__ und `.ini Data Bags `__. Um eine Seite zu übersetzen, wähle die entsprechende Sprache unten aus, öffne eine Seite und klick dann auf dieser Seite oben rechts auf "Translate on GitHub". Um Data Bags zu übersetzen, `öffne eine .ini-Datei `__ und erstelle oder bearbeite den Abschnitt für die entsprechende Sprache (z. B. [de] für Deutsch). - -Einige Seiten dieser Website sind aktuell in den folgenden Sprachen verfügbar: - - ---- -_template: translations.html diff --git a/content/contributing/how/translations/contents+es.lr b/content/contributing/how/translations/contents+es.lr index abfaddd44d..b8d2512dda 100644 --- a/content/contributing/how/translations/contents+es.lr +++ b/content/contributing/how/translations/contents+es.lr @@ -1,10 +1,7 @@ -_template: translations.html ---- body: Ayuda a traducir el contenido del sitio web! -Algunas secciones del sitio web se encuentran disponibles en los siguientes idiomas: --- title: Traducciones --- diff --git a/content/contributing/how/translations/contents+pt.lr b/content/contributing/how/translations/contents+pt.lr index 1b2c6e46b5..48820915ba 100644 --- a/content/contributing/how/translations/contents+pt.lr +++ b/content/contributing/how/translations/contents+pt.lr @@ -7,13 +7,7 @@ body: Quer ajudar a traduzir ou atualizar o conteúdo deste site? A maior parte do conteúdo destas página encontra-se em `arquivos Lektor (.lr) `__ -e `databags .ini `. Para traduzir uma página, escolha um idioma abaixo, +e `databags .ini `__. Para traduzir uma página, escolha um idioma abaixo, abra uma página e clique em "Editar no GitHub" (no canto superior direito da página). Para traduzir os databags, -`abra um arquivo .ini ` e crie ou edite a seção +`abra um arquivo .ini `__ e crie ou edite a seção para o idioma escolhido (e.g., [pt] para português). - -Algumas partes deste site estão no momento disponíveis nos seguintes idiomas: - - ---- -_template: translations.html diff --git a/content/contributing/how/translations/contents.lr b/content/contributing/how/translations/contents.lr index 4aebb7452d..8a6222ba2f 100644 --- a/content/contributing/how/translations/contents.lr +++ b/content/contributing/how/translations/contents.lr @@ -4,16 +4,27 @@ title: Translations --- body: -Want to help translate or update the content of this website? +This website +------------- -The contents of these pages are mostly written in `Lektor (.lr) files `__ -and `.ini databags `. To translate a page, select a language below, -open a page then click "Edit on GitHub" (on the top-right corner of that page). To translate the databags, -`open a .ini file ` and create or edit the section -for the specified language (e.g., [pt] for Portuguese). +Want to help translate or update the content of this website? -Some pages of this website are currently available in the following languages: +The contents of these pages are mostly written in `Lektor (.lr) files +`__ and `.ini databags +`__. To translate a page, +choose the desired langauge using the globe in the top right and then click +"Edit on GitHub". To translate the databags, `open a .ini file +`__ and +create or edit the section for the specified language (e.g., ``[pt]`` for +Portuguese). +The BeeWare Tutorial +--------------------- ---- -_template: translations.html +We also maintain translations for the `BeeWare tutorial `__. +These translations are managed using `Weblate +`__, a web interface for managing +translations. If you'd like to contribute to these translations, create an account on +Weblate, then join the ``#translations`` channel on `Discord +`__, and tell us your account username. We'll add you +to the translation team and you can get started! diff --git a/templates/translations.html b/templates/translations.html deleted file mode 100644 index f4e9b7d6d6..0000000000 --- a/templates/translations.html +++ /dev/null @@ -1,88 +0,0 @@ -{%- extends "layout.html" -%} -{%- from "macros/breadcrumbs.html" import breadcrumbs -%} -{%- from "macros/incomplete.html" import incomplete -%} -{%- from "macros/translation.html" import transbag -%} - -{%- set t_missing_translations = transbag('translate', this.alt, 'missing_translations') -%} -{%- set t_outdated_translations = transbag('translate', this.alt, 'outdated_translations') -%} - -{% block title %}{{ this.title }}{% endblock %} -{% block preamble %} - -{% endblock %} -{% block body %} -
-
- {{ incomplete(this) }} - {% block main %} - {{ this.body }} - - {% for child in this.children %} - {% if not child.hide_from_index %} -

{{ child.title }}

-

{{ child.summary }}

- {% endif %} - {% endfor %} - {% endblock %} - - {%- if this.alt != config.primary_alternative -%} -

{{ t_missing_translations }}:

- {%- for page in site.query('/', alt=this.alt) recursive -%} - {%- if not page.alt in get_alts(source=page, fallback=False) -%} -
  • - - {{ page['title'] or page['name'] or page.record_label }} - - {%- endif -%} - {%- if page.children -%} - {{- loop(page.children) -}} -
    • - {%- endif -%} - {%- endfor -%} - -

    {{ t_outdated_translations }}:

    - {%- for page in site.query('/', alt=this.alt) recursive -%} - {%- if is_alt_outdated(page) -%} -
  • - - {{ page['title'] or page['name'] or page.record_label }} - - {%- endif -%} - {%- if page.children -%} - {{- loop(page.children) -}} -
    • - {%- endif -%} - {%- endfor -%} - {%- endif -%} - -
    - {% block gutter %} - {% if this.gutter and this.gutter.source %} - -
    -
    - {{ this.gutter }} -
    -
    - {% else %} -
    -
    - {% endif %} - - {% endblock %} -
    -{% endblock %}