Update contributing docs with current practice
This commit is contained in:
Russell Martin
parent
8f71742039
commit
ff7d184070
16 changed files with 406 additions and 298 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -58,7 +58,6 @@ Bee-nevolent Dictator for Now (BDFN): `Russell Keith-Magee <https://cloudisland.
|
|||
outside open source, and code/life balance and general well-being
|
||||
is a very important thing to keep in mind.
|
||||
|
||||
|
||||
Guidelines (not actual rules)
|
||||
------------------------------
|
||||
|
||||
|
|
@ -68,7 +67,7 @@ number of general guidelines that the team should follow:
|
|||
|
||||
* **Be a good representation of the project to the wider community**
|
||||
|
||||
* **Treat every enquiry and contribution to any BeeWare project with respect.**
|
||||
* **Treat every enquiry and contribution to any BeeWare project with respect**
|
||||
|
||||
* Assume everyone has good intentions, even if they haven't chosen their
|
||||
words well
|
||||
|
|
@ -102,9 +101,7 @@ number of general guidelines that the team should follow:
|
|||
|
||||
* Acceptance processes should be automated wherever possible
|
||||
|
||||
* This means tests, linting, spell checking, coverage, and more.
|
||||
|
||||
|
||||
* This means tests, linting, spell checking, coverage, and more
|
||||
|
||||
Becoming an Apiarist
|
||||
---------------------
|
||||
|
|
|
|||
|
|
@ -15,7 +15,9 @@ There are many ways to help with BeeWare.
|
|||
`First-time Contributors`_
|
||||
---------------------------
|
||||
|
||||
If you're new to the project (or even entirely new to open source in general), the best place to start is `here </contributing/how/first-time/>`__. 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 </contributing/how/first-time/>`__. 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] <https://github.com/search?q=user%3Abeeware+label%3A%22good%20first%20issue%22+is%3Aissue+is%3Aopen&type=issues>`__.
|
||||
`[good first issue]
|
||||
<https://github.com/search?q=user%3Abeeware+label%3A%22good%20first%20issue%22+is%3Aissue+is%3Aopen&type=issues>`__.
|
||||
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,28 @@ 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!
|
||||
|
||||
Help translate and update this Website
|
||||
---------------------------------------
|
||||
|
||||
Is there anything wrong or missing from this website? Please feel free to `make edits <https://github.com/beeware/beeware.github.io>`__ and submit a pull request!
|
||||
|
||||
Want to help translate or update the content of this website? Visit the `translations section </contributing/how/translations>`__.
|
||||
Is there anything wrong or missing from this website? Please feel free to `make
|
||||
edits <https://github.com/beeware/beeware.github.io>`__ and submit a pull
|
||||
request!
|
||||
|
||||
Want to help translate or update the content of this website? Visit the
|
||||
`translations section </contributing/how/translations>`__.
|
||||
|
||||
Build a real application!
|
||||
--------------------------
|
||||
|
|
@ -80,13 +89,13 @@ 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.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,13 @@ _model: page
|
|||
---
|
||||
title: Beginners guide to DCOs
|
||||
---
|
||||
summary: Because sometimes lawyers need to get involved...
|
||||
---
|
||||
hide_from_index: yes
|
||||
---
|
||||
body: The BeeWare project uses a mechansim known as a `Developer Certificate of Origin (DCO) </contributing/how/dco/what>`__ 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...
|
||||
body: The BeeWare project uses a mechanism known as a `Developer Certificate of
|
||||
Origin (DCO) </contributing/how/dco/what>`__ 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.
|
||||
|
|
|
|||
|
|
@ -1,63 +1,116 @@
|
|||
_model: page
|
||||
---
|
||||
sort_key: 1
|
||||
---
|
||||
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 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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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*.
|
||||
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.
|
||||
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.
|
||||
Hopefully, it's clear that the terms "copyright" and "license" aren't
|
||||
interchangeable - 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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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".
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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 its
|
||||
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 </contributing/how/dco/what/>`__. For more details on what DCO is, and what it means, `see our explanatory guide </contributing/how/dco/what/>`__. 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 </contributing/how/dco/how/>`__.
|
||||
|
||||
---
|
||||
sort_key: 1
|
||||
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 </contributing/how/dco/what/>`__. For more details on what DCO is, and
|
||||
what it means, `see our explanatory guide </contributing/how/dco/what/>`__.
|
||||
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 </contributing/how/dco/how/>`__.
|
||||
|
|
|
|||
|
|
@ -2,16 +2,18 @@ _model: page
|
|||
---
|
||||
title: How to sign a DCO
|
||||
---
|
||||
summary:
|
||||
---
|
||||
incomplete: yes
|
||||
---
|
||||
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::
|
||||
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 <joe.smith@email.com>
|
||||
|
||||
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
|
||||
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``.
|
||||
|
|
|
|||
|
|
@ -1,13 +1,22 @@
|
|||
_model: page
|
||||
---
|
||||
sort_key: 2
|
||||
---
|
||||
incomplete: yes
|
||||
---
|
||||
title: What is a DCO?
|
||||
---
|
||||
body:
|
||||
|
||||
The BeeWare project uses a mechanism known as a `Developer Certificate of
|
||||
Origin (DCO) </contributing/how/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.
|
||||
|
||||
The BeeWare project uses a mechanism known as a `Developer Certificate of Origin (DCO) </contributing/how/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 <https://developercertificate.org>`__)::
|
||||
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
|
||||
<https://developercertificate.org>`__)::
|
||||
|
||||
Developer Certificate of Origin
|
||||
Version 1.1
|
||||
|
|
@ -45,15 +54,14 @@ Acknowledgement of this permission is done using a sign-off process in Git. The
|
|||
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::
|
||||
If you are willing to agree to these terms, you just add a line to every git
|
||||
commit message::
|
||||
|
||||
Signed-off-by: Joe Smith <joe.smith@email.com>
|
||||
|
||||
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``.
|
||||
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
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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 <https://github.com/watching>`_
|
||||
`watching page <https://github.com/watching>`_.
|
||||
|
||||
|
||||
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 <https://help.github.com/articles/about-notifications/>`_
|
||||
- `Managing Notifications <https://help.github.com/articles/managing-notifications/>`_
|
||||
---
|
||||
summary: So you're now using GitHub, and it's notifying you. What now?
|
||||
---
|
||||
sort_key: 4
|
||||
- `About Notifications <https://docs.github.com/articles/about-notifications>`_
|
||||
- `Managing Notifications <https://docs.github.com/articles/managing-notifications>`_
|
||||
|
|
|
|||
|
|
@ -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 <https://github.com/DjangoGirls/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 <https://github.com/DjangoGirls/tutorial>`__ which is available under
|
||||
a Creative Commons Attribution-ShareAlike 4.0 license.
|
||||
|
||||
For this tutorial, we will be using the
|
||||
`Briefcase <https://github.com/beeware/briefcase>`__ repository as a basis for the
|
||||
links and references
|
||||
For this tutorial, we will be using the `Briefcase
|
||||
<https://github.com/beeware/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 <https://github.com>`__
|
||||
- in the case of complex edits familiarity with `Git command line
|
||||
basics <https://help.github.com/articles/set-up-git/>`__ or
|
||||
familiarity with an app (`Windows and Mac <https://desktop.github.com/>`__) to push your edits made on your
|
||||
computer to GitHub.
|
||||
basics <https://docs.github.com/articles/set-up-git>`__ or
|
||||
familiarity with an app (`Windows and Mac <https://desktop.github.com/>`__)
|
||||
to push your edits made on your computer to GitHub.
|
||||
|
||||
Fork the repository
|
||||
----------------------------------
|
||||
|
||||
First fork the `Briefcase <https://github.com/beeware/briefcase>`__ repository to your
|
||||
personal GitHub account:
|
||||
First, fork the `Briefcase <https://github.com/beeware/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 <https://help.github.com/articles/about-pull-requests/>`__ 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
|
||||
<https://help.github.com/articles/about-pull-requests/>`__ 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 <https://guides.github.com/activities/contributing-to-open-source/#contributing>`__
|
||||
* `How to Fork a Repo <https://help.github.com/articles/fork-a-repo/>`__
|
||||
|
||||
* `How to Fork a Repo <https://docs.github.com/articles/fork-a-repo>`__
|
||||
|
|
|
|||
|
|
@ -1,35 +1,64 @@
|
|||
_model: page
|
||||
---
|
||||
title: Imposter Syndrome
|
||||
---
|
||||
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?
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
---
|
||||
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?
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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/
|
||||
|
||||
---
|
||||
gutter:
|
||||
|
||||
Connecting with Confident Authenticity
|
||||
----------------------------------------------
|
||||
|
||||
Learn more about how to combat imposter syndrome: watch `"Bake the Cookies, Wear the Dress" <https://www.youtube.com/watch?v=6Uj746j9Heo>`__ by Adrienne Lowe
|
||||
Learn more about how to combat imposter syndrome: watch `"Bake the Cookies,
|
||||
Wear the Dress" <https://www.youtube.com/watch?v=6Uj746j9Heo>`__ by Adrienne
|
||||
Lowe
|
||||
|
|
|
|||
|
|
@ -1,7 +1,11 @@
|
|||
_model: page
|
||||
---
|
||||
sort_key: 4
|
||||
---
|
||||
title: Setting up your environment
|
||||
---
|
||||
summary: How to get your system setup to contribute
|
||||
---
|
||||
_slug: setup
|
||||
---
|
||||
body:
|
||||
|
|
@ -17,43 +21,45 @@ 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.
|
||||
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
|
||||
</contributing/how/first-time/what-is-a/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
|
||||
</contributing/how/first-time/what-is-a/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 <https://github.com/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.
|
||||
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 </contributing/how/first-time/what-is-a/package-manager>`_, by running :code:`brew install pyenv`
|
||||
* Other - use the `automatic installer <https://github.com/pyenv/pyenv-installer>`_.
|
||||
* MacOSX - You can install pyenv via `brew
|
||||
</contributing/how/first-time/what-is-a/package-manager>`_, by running
|
||||
:code:`brew install pyenv`
|
||||
* Other - use the `automatic installer <https://github.com/pyenv/pyenv-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 <https://github.com/pyenv/pyenv/blob/master/COMMANDS.md>`_
|
||||
More information about pyenv is available on `their website
|
||||
<https://github.com/pyenv/pyenv/blob/master/COMMANDS.md>`_.
|
||||
|
||||
virtualenv
|
||||
-----------
|
||||
|
|
@ -63,33 +69,33 @@ 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.
|
||||
|
||||
One way we can do this is via `virtualenv <https://virtualenv.pypa.io/en/stable/>`_.
|
||||
One way we can do this is via `virtualenv
|
||||
<https://virtualenv.pypa.io/en/stable/>`_.
|
||||
|
||||
Using `pip </contributing/how/first-time/what-is-a/package-manager>`_, we can install virtualenv
|
||||
Using `pip </contributing/how/first-time/what-is-a/package-manager>`_, we can
|
||||
install virtualenv:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ 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
|
||||
|
||||
version of Python to use:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ virtualenv -p $(pyenv which python) env
|
||||
|
||||
Then, we can activate the virtual environment.
|
||||
|
||||
Then, we can activate the 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
|
||||
in a virtual environment:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -100,9 +106,3 @@ To disable your virtualenv:
|
|||
.. code-block:: bash
|
||||
|
||||
$ deactivate
|
||||
|
||||
|
||||
---
|
||||
summary: How to get your system setup to contribute
|
||||
---
|
||||
sort_key: 4
|
||||
|
|
|
|||
|
|
@ -2,23 +2,25 @@ _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.
|
||||
|
||||
We use a number of different CI systems: `Travis CI <https://travis-ci.com/>`_
|
||||
and `BeeKeeper <https://beekeeper.beeware.org>`_ . Normally the *build status* of a
|
||||
We primarily use GitHub's CI system: `Actions
|
||||
<https://github.com/features/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.
|
||||
|
||||
---
|
||||
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. Travis uses ``.travis.yml`` and GitHub CI is
|
||||
configured in the ``.github/workflows`` directory.
|
||||
|
|
|
|||
|
|
@ -2,19 +2,20 @@ _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.
|
||||
|
||||
However, `package managers` help make this process easier by allowing for the
|
||||
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.
|
||||
|
||||
|
||||
MacOSX
|
||||
---------------
|
||||
|
||||
|
|
@ -25,19 +26,15 @@ 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 <https://pypi.python.org/pypi>`_,
|
||||
also known as `PyPI` or "The Cheese Shop", it's a central repository for Python
|
||||
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
|
||||
<https://en.wikipedia.org/wiki/Cheese_Shop_sketch>`_ reference :)
|
||||
---
|
||||
gutter:
|
||||
---
|
||||
summary: How you can manage your installed packages
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -8,134 +8,136 @@ summary: The BeeWare development process
|
|||
---
|
||||
body:
|
||||
|
||||
Overview
|
||||
---------------
|
||||
|
||||
All changes, for code and documentation, should be `submitted
|
||||
</contributing/how/first-time/github/>`_ via a Pull Request to the GitHub
|
||||
repository for the project.
|
||||
|
||||
Most of the projects have a dedicated Contributing guide with specifics for
|
||||
that project that can be found on ReadTheDocs. For instance, Briefcase's `guide
|
||||
<https://briefcase.readthedocs.io/en/stable/how-to/contribute-code.html>`__ for
|
||||
contributing code.
|
||||
|
||||
All submissions should abide by the `Code of Conduct
|
||||
</community/behavior/code-of-conduct/>`_.
|
||||
|
||||
Change Notes
|
||||
---------------
|
||||
|
||||
Several BeeWare projects, notably Briefcase and Toga, require each Pull Request
|
||||
is submitted with a change note. These change notes are compiled together when
|
||||
a Release is cut for the project to serve as Release Notes for users.
|
||||
|
||||
`Towncrier <https://towncrier.readthedocs.io/en/stable/>`__ is used to manage
|
||||
change notes.
|
||||
|
||||
A change note file should be created in the ``changes`` directory and named
|
||||
using this format::
|
||||
|
||||
<PR/Issue #>.<Change Type>.rst
|
||||
|
||||
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 should be used
|
||||
instead.
|
||||
|
||||
All Change Types:
|
||||
|
||||
* ``feature``
|
||||
* ``bugfix``
|
||||
* ``doc``
|
||||
* ``removal``
|
||||
* ``misc``
|
||||
|
||||
The ``misc`` type is reserved for changes that do not affect users; therefore,
|
||||
they do not need to be made aware of the change for a Release. For instance,
|
||||
fixing a CI issue.
|
||||
|
||||
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 <https://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds>`__) Use
|
||||
`flake8 <https://pypi.python .org/pypi/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.
|
||||
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
|
||||
<https://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds>`__).
|
||||
|
||||
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.
|
||||
BeeWare's projects use `Pre-commit <https://pre-commit.com/>`__ 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 </contributing/how/first-time/what-is-a/ci>`_ when a Pull Request is
|
||||
opened.
|
||||
|
||||
* Use four spaces for indentation.
|
||||
To automate the Pre-commit checks in your local development environment with
|
||||
each ``git`` commit, run :code:`pre-commit install`.
|
||||
|
||||
* Use four space hanging indentation rather than vertical alignment::
|
||||
Included Pre-commit checks:
|
||||
|
||||
raise AttributeError(
|
||||
'Here is a multine error message '
|
||||
'shortened for clarity.'
|
||||
)
|
||||
* `Black <https://black.readthedocs.io/en/stable/index.html>`__ ensures uniform
|
||||
code formatting
|
||||
* `docformatter <https://docformatter.readthedocs.io/en/latest/>`__ ensures
|
||||
uniform formatting for docstrings and comments
|
||||
* `pyupgrade <https://github.com/asottile/pyupgrade>`__ ensures code is using
|
||||
the latest best practices for Python
|
||||
* `isort <https://pycqa.github.io/isort/>`__ ensures uniform ``import``
|
||||
statements
|
||||
* `flake8 <https://flake8.pycqa.org/en/latest/>`__ checks for common coding and
|
||||
syntax issues
|
||||
* Misc checks that validate structured documents such as TOML files and remove
|
||||
unnecessary whitespace
|
||||
|
||||
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".
|
||||
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.
|
||||
|
||||
* Use InitialCaps for class names (or for factory functions that return classes).
|
||||
For example::
|
||||
|
||||
* Use the Google Style Python Docstrings and :pep:`257`, type annotation with :pep:`484` is optional.
|
||||
def function_name(param1: int, param2: str) -> bool:
|
||||
"""Example function with types and a docstring.
|
||||
|
||||
::
|
||||
|
||||
def function_with_types_in_docstring(param1, param2):
|
||||
"""Example function with types documented in the docstring.
|
||||
|
||||
Args:
|
||||
param1 (int): The first parameter.
|
||||
param2 (str): The second parameter.
|
||||
|
||||
Returns:
|
||||
bool: The return value. True for success, False otherwise.
|
||||
:param param1: The first parameter.
|
||||
:param param2: The second parameter.
|
||||
|
||||
:returns: The return value. True for success, False otherwise.
|
||||
"""
|
||||
|
||||
`More examples of Google Docstrings <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`__
|
||||
|
||||
* 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::
|
||||
* 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).
|
||||
"""
|
||||
|
||||
Imports
|
||||
---------------
|
||||
|
||||
Use `isort <https://github.com/timothycrosley/isort#readme>`_ to automate
|
||||
import sorting using the guidelines below.
|
||||
|
||||
Quick start::
|
||||
|
||||
$ pip install isort
|
||||
$ isort -rc .
|
||||
|
||||
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::
|
||||
|
||||
import module # isort:skip
|
||||
|
||||
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.
|
||||
|
||||
On each line, alphabetize the items with the upper case items grouped before the lower case items.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Miscellaneous
|
||||
---------------
|
||||
|
||||
Remove ``import`` statements that are no longer used when you change code. `flake8 <https://pypi.python
|
||||
.org/pypi/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.
|
||||
"""A test docstring looks like this (#123456)."""
|
||||
|
||||
Sign your work
|
||||
---------------
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
The BeeWare project uses a mechanism known as a `Developer Certificate of Origin (DCO) </contributing/how/dco/>`__ to
|
||||
manage this process. The DCO is a legally binding statement that asserts that you are the creator of your contribution,
|
||||
The BeeWare project uses a mechanism known as a `Developer Certificate of Origin
|
||||
(DCO) </contributing/how/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.
|
||||
|
||||
To indicate that you agree to the terms of the DCO, you just add a line to every git commit message::
|
||||
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 <joe.smith@email.com>
|
||||
|
||||
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``.
|
||||
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``.
|
||||
|
||||
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 </contributing/how/dco/>`__, or `get in touch with
|
||||
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 </contributing/how/dco/>`__, or `get in touch with
|
||||
the core team </community/team>`__.
|
||||
|
|
|
|||
|
|
@ -6,14 +6,15 @@ body:
|
|||
|
||||
Want to help translate or update the content of this website?
|
||||
|
||||
The contents of these pages are mostly written in `Lektor (.lr) files <https://www.getlektor.com/docs/content/>`__
|
||||
and `.ini databags <https://www.getlektor.com/docs/content/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 <https://github.com/beeware/beeware.github.io/tree/lektor/databags>` and create or edit the section
|
||||
for the specified language (e.g., [pt] for Portuguese).
|
||||
The contents of these pages are mostly written in `Lektor (.lr) files
|
||||
<https://www.getlektor.com/docs/content/>`__ and `.ini databags
|
||||
<https://www.getlektor.com/docs/content/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
|
||||
<https://github.com/beeware/beeware.github.io/tree/lektor/databags>` and create
|
||||
or edit the section for the specified language (e.g., [pt] for Portuguese).
|
||||
|
||||
Some pages of this website are currently available in the following languages:
|
||||
|
||||
|
||||
---
|
||||
_template: translations.html
|
||||
|
|
|
|||
Loading…
Reference in a new issue