CONTRIBUTING: add more docs about what we look for in PRs
This commit unifies and extends the documentation on how to contribute: + CONTRIBUTING.md now links to the docs instead of being a dumb copy. Everything that was in there and was missing from the doc page about contributing was moved. + The _Hacking_ section is above _Contributing_ so that people who already have hacked on qtile might find it easier. + A link to the _Contributing_ page will now also be on pypi. + Most importantly, we require migrations for config-breaking changes. + We encourage people to use `git` branches for their development and require a clean commit structure. + Widgets should use the existing framework. + Unrelated changes are a no-go. Co-authored-by: Tycho Andersen <tycho@tycho.pizza>master
ep12
elParaguayo
parent
dbe248505e
commit
33d3909056
|
|
@ -1,51 +1,5 @@
|
|||
# How to contribute
|
||||
|
||||
Reporting bugs
|
||||
--------------
|
||||
|
||||
Perhaps the easiest way to contribute to Qtile is to report any bugs you
|
||||
run into on the [GitHub issue tracker](https://github.com/qtile/qtile/issues).
|
||||
|
||||
Useful bug reports are ones that get bugs fixed. A useful bug report normally
|
||||
has two qualities:
|
||||
|
||||
1. **Reproducible.** If your bug is not reproducible it will never get fixed.
|
||||
You should clearly mention the steps to reproduce the bug. Do not assume or
|
||||
skip any reproducing step. Described the issue, step-by-step, so that it is
|
||||
easy to reproduce and fix.
|
||||
|
||||
2. **Specific.** Do not write a essay about the problem. Be Specific and to the
|
||||
point. Try to summarize the problem in minimum words yet in effective way.
|
||||
Do not combine multiple problems even they seem to be similar. Write
|
||||
different reports for each problem.
|
||||
|
||||
To give more information about your bug you can append logs from
|
||||
`~/.local/share/qtile/qtile.log` or on occasionally events you can capture bugs
|
||||
with `xtrace` for this have a deeper look on the documentation about
|
||||
[capturing an xtrace](https://qtile.readthedocs.io/en/latest/manual/hacking.html#capturing-an-xtrace)
|
||||
|
||||
Writing code
|
||||
============
|
||||
|
||||
To get started writing code for Qtile, check out our guide to [hacking](https://qtile.readthedocs.io/en/latest/manual/hacking.html).
|
||||
|
||||
Submit a pull request
|
||||
---------------------
|
||||
|
||||
You've done your hacking and are ready to submit your patch to Qtile. Great!
|
||||
Now it's time to submit a [pull request](https://help.github.com/articles/using-pull-requests)
|
||||
to our [issue tracker](https://github.com/qtile/qtile/issues) on GitHub.
|
||||
|
||||
Pull requests are not considered complete until they include all of the
|
||||
following:
|
||||
|
||||
1. Code: conforms to PEP8 and passes `make lint`.
|
||||
2. Unit tests: CI tests pass. Adding new tests to verify that your code works is recommended.
|
||||
See [our website](http://docs.qtile.org/en/latest/manual/contributing.html#running-tests-locally)
|
||||
on how to run the tests locally.
|
||||
3. Documentation: Should get updated if it needed.
|
||||
|
||||
**Feel free to add your contribution (no matter how small) to the appropriate
|
||||
place in the CHANGELOG as well!**
|
||||
|
||||
Thanks
|
||||
Instead of making this document a copy of [the _contributing_ section of our
|
||||
documentation](https://docs.qtile.org/en/latest/manual/contributing.html),
|
||||
we just link to it here.
|
||||
|
|
|
|||
|
|
@ -43,8 +43,8 @@ Getting involved
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
manual/contributing
|
||||
manual/hacking
|
||||
manual/contributing
|
||||
|
||||
Miscellaneous
|
||||
=============
|
||||
|
|
|
|||
|
|
@ -25,14 +25,21 @@ has two qualities:
|
|||
|
||||
Ensure to include any appropriate log entries from
|
||||
``~/.local/share/qtile/qtile.log`` and/or ``~/.xsession-errors``!
|
||||
Sometimes, an ``xtrace`` is requested. If that is the case, refer to
|
||||
:ref:`capturing an xtrace <capturing-an-xtrace>`.
|
||||
|
||||
|
||||
Writing code
|
||||
============
|
||||
|
||||
To get started writing code for Qtile, check out our guide to :ref:`hacking`.
|
||||
|
||||
A more detailed page on creating widgets is available :ref:`here <widget-creation>`.
|
||||
|
||||
.. important::
|
||||
|
||||
Use a separate **git branch** to make rebasing easy. Ideally, you would
|
||||
``git checkout -b <my_feature_branch_name>`` before starting your work.
|
||||
|
||||
Submit a pull request
|
||||
---------------------
|
||||
|
||||
|
|
@ -48,7 +55,39 @@ to our `issue tracker <https://github.com/qtile/qtile/issues>`_ on GitHub.
|
|||
|
||||
* **Code** that conforms to PEP8.
|
||||
* **Unit tests** that pass locally and in our CI environment (More below).
|
||||
*Please add unit tests* to ensure that your code works and stays working!
|
||||
* **Documentation** updates on an as needed basis.
|
||||
* A ``qtile migrate`` **migration** is required for config-breaking changes.
|
||||
See `migrate.py <https://github.com/qtile/qtile/blob/libqtile/scripts/migrate.py>`_
|
||||
for examples and consult the `bowler documentation <https://pybowler.io>`_
|
||||
for detailed help and documentation.
|
||||
* **Code** that does not include *unrelated changes*. Examples for this are
|
||||
formatting changes, replacing quotes or whitespace in other parts of the
|
||||
code or "fixing" linter warnings popping up in your editor on existing
|
||||
code. *Do not include anything like the above!*
|
||||
* **Widgets** don't need to catch their own exceptions, or introduce their
|
||||
own polling infrastructure. The code in ``libqtile.widget.base.*`` does
|
||||
all of this. Your widget should generally only include whatever
|
||||
parsing/rendering code is necessary, any other changes should go at the
|
||||
framework level. Make sure to double-check that you are not
|
||||
re-implementing parts of ``libqtile.widget.base``.
|
||||
* **Commit messages** are more important that Github PR notes, since this is
|
||||
what people see when they are spelunking via ``git blame``. Please include
|
||||
all relevant detail in the actual git commit message (things like exact
|
||||
stack traces, copy/pastes of discussion in IRC/mailing lists, links to
|
||||
specifications or other API docs are all good). If your PR fixes a Github
|
||||
issue, it might also be wise to link to it with ``#1234`` in the commit
|
||||
message.
|
||||
* PRs with **multiple commits** should not introduce code in one patch to
|
||||
then change it in a later patch. Please do a patch-by-patch review of your
|
||||
PR, and make sure each commit passes CI and makes logical sense on its
|
||||
own. In other words: *do* introduce your feature in one commit and maybe
|
||||
add the tests and documentation in a seperate commit. *Don't* push commits
|
||||
that partially implement a feature and are basically broken.
|
||||
|
||||
.. note:: Others might ban *force-pushes*, we allow them and prefer them over
|
||||
incomplete commits or commits that have a bad and meaningless commit
|
||||
description.
|
||||
|
||||
Feel free to add your contribution (no matter how small) to the appropriate
|
||||
place in the CHANGELOG as well!
|
||||
|
|
|
|||
|
|
@ -33,6 +33,8 @@ traceback of an error to the log. By sticking these amongst your changes you
|
|||
can look more closely at the effects of any changes you made to Qtile's
|
||||
internals.
|
||||
|
||||
.. _capturing-an-xtrace:
|
||||
|
||||
Capturing an ``xtrace``
|
||||
=======================
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue