Merge branch 'v0.6' into fabric_task_improvements
coffeedogs
5 years ago
committed by
coffeedogs
commit
7e2cb2176e
@ -1,15 +1,33 @@
|
||||
## Code contributions to the Bitmessage project
|
||||
## Repository contributions to the PyBitmessage project
|
||||
|
||||
- try to explain what the code is about
|
||||
- try to follow [PEP0008](https://www.python.org/dev/peps/pep-0008/)
|
||||
- make the pull request against the ["v0.6" branch](https://github.com/Bitmessage/PyBitmessage/tree/v0.6)
|
||||
- PGP-sign the commits included in the pull request
|
||||
- try to use a good editor that removes trailing whitespace, highlights potential python issues and uses unix line endings
|
||||
- You can get paid for merged commits if you register at [Tip4Commit](https://tip4commit.com/github/Bitmessage/PyBitmessage)
|
||||
|
||||
If for some reason you don't want to use github, you can submit the patch using Bitmessage to the "bitmessage" chan, or to one of the developers.
|
||||
### Code
|
||||
|
||||
- Try to refer to github issue tracker or other permanent sources of discussion about the issue.
|
||||
- It is clear from the diff *what* you have done, it may be less clear *why* you have done it so explain why this change is necessary rather than what it does
|
||||
|
||||
### Documentation
|
||||
|
||||
- If there has been a change to the code, there's a good possibility there should be a corresponding change to the documentation
|
||||
- If you can't run `fab build_docs` successfully, ask for someone to run it against your branch
|
||||
|
||||
### Tests
|
||||
|
||||
- If there has been a change to the code, there's a good possibility there should be a corresponding change to the tests
|
||||
- If you can't run `fab tests` successfully, ask for someone to run it against your branch
|
||||
|
||||
## Translations
|
||||
|
||||
For helping with translations, please use [Transifex](https://www.transifex.com/bitmessage-project/pybitmessage/). There is no need to submit pull requests for translations.
|
||||
For translating technical terms it is recommended to consult the [Microsoft Language Portal](https://www.microsoft.com/Language/en-US/Default.aspx).
|
||||
- For helping with translations, please use [Transifex](https://www.transifex.com/bitmessage-project/pybitmessage/).
|
||||
- There is no need to submit pull requests for translations.
|
||||
- For translating technical terms it is recommended to consult the [Microsoft Language Portal](https://www.microsoft.com/Language/en-US/Default.aspx).
|
||||
|
||||
### Gitiquette
|
||||
|
||||
- Make the pull request against the ["v0.6" branch](https://github.com/Bitmessage/PyBitmessage/tree/v0.6)
|
||||
- PGP-sign the commits included in the pull request
|
||||
- Use references to tickets, e.g. `addresses #123` or `fixes #234` in your commit messages
|
||||
- Try to use a good editor that removes trailing whitespace, highlights potential python issues and uses unix line endings
|
||||
- If for some reason you don't want to use github, you can submit the patch using Bitmessage to the "bitmessage" chan, or to one of the developers.
|
||||
|
||||
|
||||
@ -0,0 +1,20 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
SPHINXPROJ = PyBitmessage
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
@ -0,0 +1,210 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
Configuration file for the Sphinx documentation builder.
|
||||
|
||||
This file does only contain a selection of the most common options. For a
|
||||
full list see the documentation:
|
||||
http://www.sphinx-doc.org/en/master/config
|
||||
|
||||
-- Path setup --------------------------------------------------------------
|
||||
|
||||
If extensions (or modules to document with autodoc) are in another directory,
|
||||
add these directories to sys.path here. If the directory is relative to the
|
||||
documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
"""
|
||||
|
||||
import os
|
||||
import sys
|
||||
|
||||
from sphinx.apidoc import main
|
||||
from mock import Mock as MagicMock
|
||||
|
||||
sys.path.insert(0, os.path.abspath('.'))
|
||||
sys.path.insert(0, os.path.abspath('..'))
|
||||
sys.path.insert(0, os.path.abspath('../src'))
|
||||
sys.path.insert(0, os.path.abspath('../src/pyelliptic'))
|
||||
|
||||
import version
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = u'PyBitmessage'
|
||||
copyright = u'2018, The Bitmessage Team' # pylint: disable=redefined-builtin
|
||||
author = u'The Bitmessage Team'
|
||||
|
||||
# The short X.Y version
|
||||
version = unicode(version.softwareVersion)
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = version
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
#
|
||||
# needs_sphinx = '1.0'
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
# 'sphinx.ext.doctest', # Currently disabled due to bad doctests
|
||||
'sphinx.ext.intersphinx',
|
||||
'sphinx.ext.todo',
|
||||
'sphinx.ext.coverage',
|
||||
'sphinx.ext.imgmath',
|
||||
'sphinx.ext.viewcode',
|
||||
'm2r',
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
#
|
||||
source_suffix = ['.rst', '.md']
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path .
|
||||
exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'alabaster'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#
|
||||
# html_theme_options = {}
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
|
||||
# Custom sidebar templates, must be a dictionary that maps document names
|
||||
# to template names.
|
||||
#
|
||||
# The default sidebars (for documents that don't match any pattern) are
|
||||
# defined by theme itself. Builtin themes are using these templates by
|
||||
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
|
||||
# 'searchbox.html']``.
|
||||
#
|
||||
# html_sidebars = {}
|
||||
|
||||
# Deal with long lines in source view
|
||||
html_theme_options = {
|
||||
'page_width': '1366px',
|
||||
}
|
||||
|
||||
# -- Options for HTMLHelp output ---------------------------------------------
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'PyBitmessagedoc'
|
||||
|
||||
|
||||
# -- Options for LaTeX output ------------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#
|
||||
# 'papersize': 'letterpaper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#
|
||||
# 'pointsize': '10pt',
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#
|
||||
# 'preamble': '',
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#
|
||||
# 'figure_align': 'htbp',
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, 'PyBitmessage.tex', u'PyBitmessage Documentation',
|
||||
u'The Bitmessage Team', 'manual'),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for manual page output ------------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
(master_doc, 'pybitmessage', u'PyBitmessage Documentation',
|
||||
[author], 1)
|
||||
]
|
||||
|
||||
|
||||
# -- Options for Texinfo output ----------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, 'PyBitmessage', u'PyBitmessage Documentation',
|
||||
author, 'PyBitmessage', 'One line description of project.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for Epub output -------------------------------------------------
|
||||
|
||||
# Bibliographic Dublin Core info.
|
||||
epub_title = project
|
||||
epub_author = author
|
||||
epub_publisher = author
|
||||
epub_copyright = copyright
|
||||
|
||||
# The unique identifier of the text. This can be a ISBN number
|
||||
# or the project homepage.
|
||||
#
|
||||
# epub_identifier = ''
|
||||
|
||||
# A unique identification for the text.
|
||||
#
|
||||
# epub_uid = ''
|
||||
|
||||
# A list of files that should not be packed into the epub file.
|
||||
epub_exclude_files = ['search.html']
|
||||
|
||||
|
||||
# -- Extension configuration -------------------------------------------------
|
||||
|
||||
# -- Options for intersphinx extension ---------------------------------------
|
||||
|
||||
# Example configuration for intersphinx: refer to the Python standard library.
|
||||
intersphinx_mapping = {'https://docs.python.org/': None}
|
||||
|
||||
# -- Options for todo extension ----------------------------------------------
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = True
|
||||
@ -0,0 +1,18 @@
|
||||
Documentation
|
||||
=============
|
||||
|
||||
Sphinx is used to pull richly formatted comments out of code, merge them with hand-written documentation and render it
|
||||
in HTML and other formats.
|
||||
|
||||
To build the docs, simply run `$ fab -H localhost build_docs` once you have set up Fabric.
|
||||
|
||||
Restructured Text (RsT) vs MarkDown (md)
|
||||
----------------------------------------
|
||||
|
||||
There's much on the internet about this. Suffice to say RsT_ is preferred for Python documentation while md is preferred for web markup or for certain other languages.
|
||||
|
||||
.. _Rst: [http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html]` style is preferred,
|
||||
|
||||
`md` files can also be incorporated by using mdinclude directives in the indices. They are translated to RsT before rendering to the various formats. Headers are translated as a hard-coded level `(H1: =, H2: -, H3: ^, H4: ~, H5: ", H6: #`. This represents a small consideration for both styles. If markup is not translated to rst well enough, switch to rst.
|
||||
|
||||
|
||||
@ -0,0 +1,2 @@
|
||||
.. mdinclude:: fabfile/README.md
|
||||
|
||||
@ -0,0 +1,38 @@
|
||||
Operational Security
|
||||
====================
|
||||
|
||||
Bitmessage has many features that are designed to protect your anonymity during normal use. There are other things that you must or should do if you value your anonymity.
|
||||
|
||||
Castles in the sand
|
||||
-------------------
|
||||
|
||||
You cannot build a strong castle on unstable foundations. If your operating system is not wholly owned by you then it is impossible to make guarantees about an application.
|
||||
|
||||
* Carefully choose your operating system
|
||||
* Ensure your operating system is up to date
|
||||
* Ensure any dependencies and requirements are up to date
|
||||
|
||||
Extrordinary claims require extrordinary evidence
|
||||
-------------------------------------------------
|
||||
|
||||
If we are to make bold claims about protecting your privacy we should demonstrate this by strong actions.
|
||||
|
||||
- PGP signed commits
|
||||
- looking to audit
|
||||
- warrant canary
|
||||
|
||||
Digital foootprint
|
||||
------------------
|
||||
|
||||
Your internet use can reveal metadata you wouldn't expect. This can be connected with other information about you if you're not careful.
|
||||
|
||||
* Use separate addresses for different puprose
|
||||
* Don't make the same mistakes all the time
|
||||
* Your language use is unique. The more you type, the more you fingerprint yourself. The words you know and use often vs the words you don't know or use often.
|
||||
|
||||
Cleaning history
|
||||
----------------
|
||||
|
||||
* Tell your browser not to store BitMessage addresses
|
||||
* Microsoft Office seems to offer the ability to define sensitive informations types. If browsers don't already they may in the future. Consider adding `BM-\w{x..y}`.
|
||||
|
||||
@ -0,0 +1,88 @@
|
||||
Developing
|
||||
==========
|
||||
|
||||
Devops tasks
|
||||
------------
|
||||
|
||||
Bitmessage makes use of fabric_ to define tasks such as building documentation or running checks and tests on the code. If you can install
|
||||
|
||||
.. _fabric: https://fabfile.org
|
||||
|
||||
Code style and linters
|
||||
----------------------
|
||||
|
||||
We aim to be PEP8 compliant but we recognise that we have a long way still to go. Currently we have style and lint exceptions specified at the most specific place we can. We are ignoring certain issues project-wide in order to avoid alert-blindess, avoid style and lint regressions and to allow continuous integration to hook into the output from the tools. While it is hoped that all new changes pass the checks, fixing some existing violations are mini-projects in themselves. Current thinking on ignorable violations is reflected in the options and comments in setup.cfg. Module and line-level lint warnings represent refactoring opportunities.
|
||||
|
||||
Pull requests
|
||||
-------------
|
||||
|
||||
There is a template at PULL_REQUEST_TEMPLATE.md that appears in the pull-request description. Please replace this text with something appropriate to your changes based off the ideas in the template.
|
||||
|
||||
Bike-shedding
|
||||
-------------
|
||||
|
||||
Beyond having well-documented, Pythonic code with static analysis tool checks, extensive test coverage and powerful devops tools, what else can we have? Without violating any linters there is room for making arbirary decisions solely for the sake of project consistency. These are the stuff of the pedant's PR comments. Rather than have such conversations in PR comments, we can lay out the result of discussion here.
|
||||
|
||||
I'm putting up a strawman for each topic here, mostly based on my memory of reading related Stack Overflow articles etc. If contributors feel strongly (and we don't have anything better to do) then maybe we can convince each other to update this section.
|
||||
|
||||
Trailing vs hanging braces
|
||||
Data
|
||||
Hanging closing brace is preferred, trailing commas always to help reduce churn in diffs
|
||||
Function, class, method args
|
||||
Inline until line-length, then style as per data
|
||||
Nesting
|
||||
Functions
|
||||
Short: group hanging close parentheses
|
||||
Long: one closing parentheses per line
|
||||
|
||||
Single vs double quotes
|
||||
Single quotes are preferred; less strain on the hands, eyes
|
||||
|
||||
Double quotes are only better so as to contain single quotes, but we want to contain doubles as often
|
||||
|
||||
Line continuation
|
||||
Implicit parentheses continuation is preferred
|
||||
|
||||
British vs American spelling
|
||||
We should be consistent, it looks like we have American to British at approx 140 to 60 in the code. There's not enough occurrences that we couldn't be consistent one way or the other. It breaks my heart that British spelling could lose this one but I'm happy to 'z' things up for the sake of consistency. So I put forward British to be preferred. Either that strawman wins out, or I incite interest in ~bike-shedding~ guiding the direction of this crucial topic from others.
|
||||
|
||||
Dependency graph
|
||||
----------------
|
||||
|
||||
These images are not very useful right now but the aim is to tweak the settings of one or more of them to be informative, and/or divide them up into smaller grapghs.
|
||||
|
||||
To re-build them, run `fab build_docs:dep_graphs=true`. Note that the dot graph takes a lot of time.
|
||||
|
||||
.. figure:: ../../../../_static/deps-neato.png
|
||||
:alt: neato graph of dependencies
|
||||
:width: 100 pc
|
||||
|
||||
:index:`Neato` graph of dependencies
|
||||
|
||||
.. figure:: ../../../../_static/deps-sfdp.png
|
||||
:alt: SFDP graph of dependencies
|
||||
:width: 100 pc
|
||||
|
||||
:index:`SFDP` graph of dependencies
|
||||
|
||||
.. figure:: ../../../../_static/deps-dot.png
|
||||
:alt: Dot graph of dependencies
|
||||
:width: 100 pc
|
||||
|
||||
:index:`Dot` graph of dependencies
|
||||
|
||||
Key management
|
||||
--------------
|
||||
|
||||
Nitro key
|
||||
^^^^^^^^^
|
||||
|
||||
Regular contributors are enouraged to take further steps to protect their key and the Nitro Key (Start) is recommended by the BitMessage project for this purpose.
|
||||
|
||||
Debian-quirks
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Stretch makes use of the directory ~/.gnupg/private-keys-v1.d/ to store the private keys. This simplifies some steps of the Nitro Key instructions. See step 5 of Debian's subkeys_ wiki page
|
||||
|
||||
.. _subkeys: https://wiki.debian.org/Subkeys
|
||||
|
||||
@ -0,0 +1,4 @@
|
||||
Testing
|
||||
=======
|
||||
|
||||
Currently there is a Travis job somewhere which runs python setup.py test. This doesn't find any tests when run locally for some reason.
|
||||
@ -0,0 +1,4 @@
|
||||
TODO list
|
||||
=========
|
||||
|
||||
.. todolist::
|
||||
@ -0,0 +1,8 @@
|
||||
Developing
|
||||
==========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:glob:
|
||||
|
||||
develop.dir/*
|
||||
@ -0,0 +1,28 @@
|
||||
Processes
|
||||
=========
|
||||
|
||||
In other to keep the Bitmessage project running the team run a number of systems and accounts that form the
|
||||
development pipeline and continuous delivery process. We are always striving to improve the process. Towards
|
||||
that end it is documented here.
|
||||
|
||||
|
||||
Project website
|
||||
---------------
|
||||
|
||||
The bitmessage website_
|
||||
|
||||
Github
|
||||
------
|
||||
|
||||
Our official Github_ account is Bitmessage. Our issue tracker is here as well.
|
||||
|
||||
|
||||
BitMessage
|
||||
----------
|
||||
|
||||
We eat our own dog food! You can send us bug reports via the Bitmessage chan at xxx
|
||||
|
||||
|
||||
.. _website: https://bitmessage.org
|
||||
.. _Github: https://github.com/Bitmessage/PyBitmessage
|
||||
|
||||
@ -0,0 +1,25 @@
|
||||
Contributing
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:glob:
|
||||
|
||||
contribute.dir/*
|
||||
|
||||
|
||||
- Report_
|
||||
- Develop_(develop)
|
||||
- Translate_
|
||||
- Donate_
|
||||
- Fork the code and open a PR_ on github
|
||||
- Search the `issue tracker` on github or open a new issue
|
||||
- Send bug report to the chan
|
||||
|
||||
.. _Report: https://github.com/Bitmessage/PyBitmessage/issues
|
||||
.. _Develop: https://github.com/Bitmessage/PyBitmessage
|
||||
.. _Translate: https://www.transifex.com/bitmessage-project/pybitmessage/
|
||||
.. _Donate: https://tip4commit.com/github/Bitmessage/PyBitmessage
|
||||
.. _PR: https://github.com/Bitmessage/PyBitmessage/pulls
|
||||
.. _`issue tracker`: https://github.com/Bitmessage/PyBitmessage/issues
|
||||
contributing/*
|
||||
@ -0,0 +1,15 @@
|
||||
.. mdinclude:: ../README.md
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
overview
|
||||
usage
|
||||
contribute
|
||||
|
||||
Indices and tables
|
||||
------------------
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
@ -0,0 +1,36 @@
|
||||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=.
|
||||
set BUILDDIR=_build
|
||||
set SPHINXPROJ=PyBitmessage
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.http://sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
|
||||
|
||||
:end
|
||||
popd
|
||||
@ -0,0 +1,21 @@
|
||||
Usage
|
||||
=====
|
||||
|
||||
GUI
|
||||
---
|
||||
|
||||
Bitmessage has a PyQT GUI_
|
||||
|
||||
CLI
|
||||
---
|
||||
|
||||
Bitmessage has a CLI_
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
Bitmessage has an XML-RPC API_
|
||||
|
||||
.. _GUI: https://bitmessage.org/wiki/PyBitmessage_Help
|
||||
.. _CLI: https://bitmessage.org/wiki/PyBitmessage_Help
|
||||
.. _API: https://bitmessage.org/wiki/API_Reference
|
||||