Don't include docs fetched-at-build-time in Git repo
This commit is contained in:
Troy McConaghy
parent
3566c97873
commit
4fb963d149
|
|
@ -92,3 +92,6 @@ terraform.tfstate.backup
|
|||
# tendermint data
|
||||
tmdata/data
|
||||
network/*/data
|
||||
|
||||
# Docs that are fetched at build time
|
||||
docs/contributing/source/cross-project-policies/*.md
|
||||
|
|
|
|||
|
|
@ -1,50 +0,0 @@
|
|||
# Contributor Code of Conduct
|
||||
|
||||
As contributors and maintainers of this project, and in the interest of
|
||||
fostering an open and welcoming community, we pledge to respect all people who
|
||||
contribute to the project.
|
||||
|
||||
We are committed to making participation in this project a harassment-free
|
||||
experience for everyone, regardless of level of experience, gender, gender
|
||||
identity and expression, sexual orientation, disability, personal appearance,
|
||||
body size, race, ethnicity, age, religion, nationality, or species--no picking on Wrigley for being a buffalo!
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
|
||||
* The use of sexualized language or imagery
|
||||
* Personal attacks
|
||||
* Trolling or insulting/derogatory comments
|
||||
* Public or private harassment
|
||||
* Publishing other's private information, such as physical or electronic
|
||||
addresses, without explicit permission
|
||||
* Deliberate intimidation
|
||||
* Other unethical or unprofessional conduct
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or
|
||||
reject comments, commits, code, wiki edits, issues, and other contributions
|
||||
that are not aligned to this Code of Conduct, or to ban temporarily or
|
||||
permanently any contributor for other behaviors that they deem inappropriate,
|
||||
threatening, offensive, or harmful.
|
||||
|
||||
By adopting this Code of Conduct, project maintainers commit themselves to
|
||||
fairly and consistently applying these principles to every aspect of managing
|
||||
this project. Project maintainers who do not follow or enforce the Code of
|
||||
Conduct may be permanently removed from the project team.
|
||||
|
||||
This Code of Conduct applies both within project spaces and in public spaces
|
||||
when an individual is representing the project or its community.
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior directed at yourself or another community member may be
|
||||
reported by contacting a project maintainer at [conduct@bigchaindb.com](mailto:conduct@bigchaindb.com). All
|
||||
complaints will be reviewed and investigated and will result in a response that
|
||||
is appropriate to the circumstances. Maintainers are
|
||||
obligated to maintain confidentiality with regard to the reporter of an
|
||||
incident.
|
||||
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
|
||||
version 1.3.0, available at
|
||||
[http://contributor-covenant.org/version/1/3/0/][version]
|
||||
|
||||
[homepage]: http://contributor-covenant.org
|
||||
[version]: http://contributor-covenant.org/version/1/3/0/
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,90 +0,0 @@
|
|||
# Python Style Guide
|
||||
|
||||
This guide starts out with our general Python coding style guidelines and ends with a section on how we write & run (Python) tests.
|
||||
|
||||
## General Python Coding Style Guidelines
|
||||
|
||||
Our starting point is [PEP8](https://www.python.org/dev/peps/pep-0008/), the standard "Style Guide for Python Code." Many Python IDEs will check your code against PEP8. (Note that PEP8 isn't frozen; it actually changes over time, but slowly.)
|
||||
|
||||
BigchainDB uses Python 3.5+, so you can ignore all PEP8 guidelines specific to Python 2.
|
||||
|
||||
We use [pre-commit](http://pre-commit.com/) to check some of the rules below before every commit but not everything is realized yet.
|
||||
The hooks we use can be found in the [.pre-commit-config.yaml](https://github.com/bigchaindb/bigchaindb/blob/master/.pre-commit-config.yaml) file.
|
||||
|
||||
### Python Docstrings
|
||||
|
||||
PEP8 says some things about docstrings, but not what to put in them or how to structure them. [PEP257](https://www.python.org/dev/peps/pep-0257/) was one proposal for docstring conventions, but we prefer [Google-style docstrings](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments) instead: they're easier to read and the [napoleon extension](http://www.sphinx-doc.org/en/stable/ext/napoleon.html) for Sphinx lets us turn them into nice-looking documentation. Here are some references on Google-style docstrings:
|
||||
|
||||
* [Google's docs on Google-style docstrings](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments)
|
||||
* [napoleon's docs include an overview of Google-style docstrings](http://sphinxcontrib-napoleon.readthedocs.org/en/latest/index.html)
|
||||
* [Example Google-style docstrings](http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html) (from napoleon's docs)
|
||||
|
||||
### Maximum Line Length
|
||||
|
||||
PEP8 has some [maximum line length guidelines](https://www.python.org/dev/peps/pep-0008/#id17), starting with "Limit all lines to a maximum of 79 characters" but "for flowing long blocks of text with fewer structural restrictions (docstrings or comments), the line length should be limited to 72 characters."
|
||||
|
||||
We discussed this at length, and it seems that the consensus is: _try_ to keep line lengths less than 79/72 characters, unless you have a special situation where longer lines would improve readability. (The basic reason is that 79/72 works for everyone, and BigchainDB is an open source project.) As a hard limit, keep all lines less than 119 characters (which is the width of GitHub code review).
|
||||
|
||||
### Single or Double Quotes?
|
||||
|
||||
Python lets you use single or double quotes. PEP8 says you can use either, as long as you're consistent. We try to stick to using single quotes, except in cases where using double quotes is more readable. For example:
|
||||
```python
|
||||
print('This doesn\'t look so nice.')
|
||||
print("Doesn't this look nicer?")
|
||||
```
|
||||
|
||||
### Breaking Strings Across Multiple Lines
|
||||
|
||||
Should we use parentheses or slashes (`\`) to break strings across multiple lines, i.e.
|
||||
```python
|
||||
my_string = ('This is a very long string, so long that it will not fit into just one line '
|
||||
'so it must be split across multiple lines.')
|
||||
# or
|
||||
my_string = 'This is a very long string, so long that it will not fit into just one line ' \
|
||||
'so it must be split across multiple lines.'
|
||||
```
|
||||
|
||||
It seems the preference is for slashes, but using parentheses is okay too. (There are good arguments either way. Arguing about it seems like a waste of time.)
|
||||
|
||||
### How to Format Long import Statements
|
||||
|
||||
If you need to `import` lots of names from a module or package, and they won't all fit in one line (without making the line too long), then use parentheses to spread the names across multiple lines, like so:
|
||||
```python
|
||||
from Tkinter import (
|
||||
Tk, Frame, Button, Entry, Canvas, Text,
|
||||
LEFT, DISABLED, NORMAL, RIDGE, END,
|
||||
)
|
||||
|
||||
# Or
|
||||
|
||||
from Tkinter import (Tk, Frame, Button, Entry, Canvas, Text,
|
||||
LEFT, DISABLED, NORMAL, RIDGE, END)
|
||||
```
|
||||
|
||||
For the rationale, see [PEP 328](https://www.python.org/dev/peps/pep-0328/#rationale-for-parentheses).
|
||||
|
||||
### Using the % operator or `format()` to Format Strings
|
||||
|
||||
Given the choice:
|
||||
```python
|
||||
x = 'name: %s; score: %d' % (name, n)
|
||||
# or
|
||||
x = 'name: {}; score: {}'.format(name, n)
|
||||
```
|
||||
|
||||
we use the `format()` version. The [official Python documentation says](https://docs.python.org/2/library/stdtypes.html#str.format), "This method of string formatting is the new standard in Python 3, and should be preferred to the % formatting described in String Formatting Operations in new code."
|
||||
|
||||
|
||||
## Running the Flake8 Style Checker
|
||||
|
||||
We use [Flake8](http://flake8.pycqa.org/en/latest/index.html) to check our Python code style. Once you have it installed, you can run it using:
|
||||
```text
|
||||
flake8 --max-line-length 119 bigchaindb/
|
||||
```
|
||||
|
||||
|
||||
## Writing and Running (Python) Tests
|
||||
|
||||
The content of this section was moved to [`bigchaindb/tests/README.md`](./tests/README.md).
|
||||
|
||||
Note: We automatically run all tests on all pull requests (using Travis CI), so you should definitely run all tests locally before you submit a pull request. See the above-linked README file for instructions.
|
||||
|
|
@ -1,73 +0,0 @@
|
|||
# Our Release Process
|
||||
|
||||
The release process for BigchainDB server differs slightly depending on whether it's a minor or a patch release.
|
||||
|
||||
BigchainDB follows
|
||||
[the Python form of Semantic Versioning](https://packaging.python.org/tutorials/distributing-packages/#choosing-a-versioning-scheme)
|
||||
(i.e. MAJOR.MINOR.PATCH),
|
||||
which is almost identical
|
||||
to [regular semantic versioning](http://semver.org/)
|
||||
except release candidates are labelled like
|
||||
`3.4.5rc2` not `3.4.5-rc2` (with no hyphen).
|
||||
|
||||
|
||||
## Minor release
|
||||
|
||||
A minor release is preceeded by a feature freeze and created from the 'master' branch. This is a summary of the steps we go through to release a new minor version of BigchainDB Server.
|
||||
|
||||
1. Update the `CHANGELOG.md` file in master
|
||||
1. In `k8s/bigchaindb/bigchaindb-dep.yaml` AND in `k8s/dev-setup/bigchaindb.yaml`, find the line of the form `image: bigchaindb/bigchaindb:0.8.1` and change the version number to the new version number, e.g. `0.9.0`. (This is the Docker image that Kubernetes should pull from Docker Hub.) Commit that change to master
|
||||
1. Create and checkout a new branch for the minor release, named after the minor version, without a preceeding 'v', e.g. `git checkout -b 0.9` (*not* 0.9.0, this new branch will be for e.g. 0.9.0, 0.9.1, 0.9.2, etc. each of which will be identified by a tagged commit)
|
||||
1. Push the new branch to GitHub, e.g. `git push origin 0.9`
|
||||
1. Create and checkout a new branch off of the 0.9 branch. Let's call it branch T for now
|
||||
1. In `bigchaindb/version.py`, update `__version__` and `__short_version__`, e.g. to `0.9` and `0.9.0` (with no `.dev` on the end)
|
||||
1. Commit those changes, push the new branch T to GitHub, and use the pushed branch T to create a new pull request merging the T branch into the 0.9 branch.
|
||||
1. Wait for all the tests to pass! Then merge T into 0.9.
|
||||
1. Follow steps outlined in [Common Steps](#common-steps)
|
||||
1. In 'master' branch, Edit `bigchaindb/version.py`, increment the minor version to the next planned release, e.g. `0.10.0.dev`. (Exception: If you just released `X.Y.Zrc1` then increment the minor version to `X.Y.Zrc2`.) This step is so people reading the latest docs will know that they're for the latest (master branch) version of BigchainDB Server, not the docs at the time of the most recent release (which are also available).
|
||||
1. Go to [Docker Hub](https://hub.docker.com/), sign in, go to bigchaindb/bigchaindb, go to Settings - Build Settings, and under the build with Docker Tag Name equal to `latest`, change the Name to the number of the new release, e.g. `0.9`
|
||||
|
||||
Congratulations, you have released BigchainDB!
|
||||
|
||||
## Patch release
|
||||
|
||||
A patch release is similar to a minor release, but piggybacks on an existing minor release branch:
|
||||
|
||||
1. Check out the minor release branch, e.g. `0.9`
|
||||
1. Apply the changes you want, e.g. using `git cherry-pick`.
|
||||
1. Update the `CHANGELOG.md` file
|
||||
1. Increment the patch version in `bigchaindb/version.py`, e.g. `0.9.1`
|
||||
1. Commit that change
|
||||
1. In `k8s/bigchaindb/bigchaindb-dep.yaml` AND in `k8s/dev-setup/bigchaindb.yaml`, find the line of the form `image: bigchaindb/bigchaindb:0.9.0` and change the version number to the new version number, e.g. `0.9.1`. (This is the Docker image that Kubernetes should pull from Docker Hub.)
|
||||
1. Commit that change
|
||||
1. Push the updated minor release branch to GitHub
|
||||
1. Follow steps outlined in [Common Steps](#common-steps)
|
||||
1. Cherry-pick the `CHANGELOG.md` update commit (made above) to the `master` branch
|
||||
|
||||
## Common steps
|
||||
|
||||
These steps are common between minor and patch releases:
|
||||
|
||||
1. Go to the [bigchaindb/bigchaindb Releases page on GitHub](https://github.com/bigchaindb/bigchaindb/releases)
|
||||
and click the "Draft a new release" button
|
||||
1. Fill in the details:
|
||||
- Tag version: version number preceeded by 'v', e.g. "v0.9.1"
|
||||
- Target: the release branch that was just pushed
|
||||
- Title: Same as tag name above, e.g "v0.9.1"
|
||||
- Description: The body of the changelog entry (Added, Changed, etc.)
|
||||
1. Click "Publish release" to publish the release on GitHub
|
||||
1. Make sure your local Git is in the same state as the release: e.g. `git fetch <remote-name>` and `git checkout v0.9.1`
|
||||
1. Make sure you have a `~/.pypirc` file containing credentials for PyPI
|
||||
1. Do a `make release` to build and publish the new `bigchaindb` package on PyPI
|
||||
1. [Login to readthedocs.org](https://readthedocs.org/accounts/login/) and go to the **BigchainDB Server** project (*not* **BigchainDB**), then:
|
||||
- Go to Admin --> Advanced Settings
|
||||
and make sure that "Default branch:" (i.e. what "latest" points to)
|
||||
is set to the new release's tag, e.g. `v0.9.1`.
|
||||
(Don't miss the 'v' in front.)
|
||||
- Go to Admin --> Versions
|
||||
and under **Choose Active Versions**, do these things:
|
||||
1. Make sure that the new version's tag is "Active" and "Public"
|
||||
2. Make sure the new version's branch
|
||||
(without the 'v' in front) is _not_ active.
|
||||
3. Make sure the **stable** branch is _not_ active.
|
||||
4. Scroll to the bottom of the page and click the Submit button.
|
||||
|
|
@ -1,34 +0,0 @@
|
|||
# Shared Workspace Protocol
|
||||
```
|
||||
shortname: 6/SWP
|
||||
name: Shared Workspace Protocol
|
||||
type: Meta
|
||||
status: Draft
|
||||
editor: Alberto Granzotto <alberto@bigchaindb.com>
|
||||
```
|
||||
|
||||
## Abstract
|
||||
The "Shared Workspace Protocol" provides a simple set of rules for people working in the same workspace.
|
||||
|
||||
## Motivation
|
||||
Focusing in a shared workspace (or in the office in general) can be a really challenging task. Working from home solves the problem, but it is not an ideal solution if forced by the difficulty to focus in the office.
|
||||
|
||||
## Language
|
||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) \[[RFC2119](https://tools.ietf.org/html/rfc2119)\] \[[RFC8174](https://tools.ietf.org/html/rfc8174)\] when, and only when, they appear in all capitals, as shown here.
|
||||
|
||||
## Rationale
|
||||
SWP provides a reusable collaboration model for people working in the same workspace. It has these specific goals:
|
||||
|
||||
1. To maximize focus and productivity, by reducing the sources of distraction.
|
||||
1. To reduce the burden to ask people to "behave" or "leave the room", by having an explicit protocol people agree before entering the room.
|
||||
|
||||
## Implementation
|
||||
1. When implemented, this protocol MUST be visible at the entrance of the shared workspace.
|
||||
1. A person SHOULD write a message to another person before speaking with them.
|
||||
1. A person SHOULD NOT be loud.
|
||||
1. A person SHOULD NOT talk to more than one person at a time.
|
||||
1. One-on-one conversations MUST be short and occasional.
|
||||
1. A person MUST NOT have calls unless everyone in the room is involved.
|
||||
|
||||
## Copyright Waiver
|
||||
To the extent possible under law, the person who associated CC0 with this work has waived all copyright and related or neighboring rights to this work.
|
||||
Loading…
Reference in New Issue