From 9ba769b04971cc9445e8a834486325d15c240f5c Mon Sep 17 00:00:00 2001 From: anonimal Date: Thu, 18 Feb 2016 01:45:40 +0000 Subject: [PATCH] License/Docs: update/cleanup documentation. --- README.md | 28 +++++++++++++---------- doc/CONTRIBUTING.md | 45 ++++++++++++++++++++++++++++++++++++ doc/FAQ.md | 16 +++++-------- doc/STYLE.md | 56 --------------------------------------------- 4 files changed, 67 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index 9c1bf7cb..fcc45428 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,33 @@ # **ˈKɔːvrɪ** 1. To cover, veil, wrap *[(Esperanto)](https://en.wikipedia.org/wiki/Esperanto)* -2. The secure, private, untraceable C++ router implementation of the [I2P](https://geti2p.net) anonymous network, +2. The secure, private, untraceable C++ implementation of the [I2P](https://geti2p.net) anonymous network, [![Build Status](https://travis-ci.org/monero-project/kovri.svg?branch=master)](https://travis-ci.org/monero-project/kovri) [![Documentation](https://codedocs.xyz/monero-project/kovri.svg)](https://codedocs.xyz/monero-project/kovri/) ## Disclaimer -- Currently pre-alpha software; under heavy overhaul and development! Stick to branch ```master``` for stability. -- See branch ```development``` for the meat of Kovri evolution. +- Currently pre-alpha software; under heavy development! +- Use branch ```master``` for more stability. +- See branch ```development``` for most recent activity. ## Quickstart -1. Download/install the **latest** [CMake](https://cmake.org/), [Boost](http://www.boost.org/), [Crypto++](https://cryptopp.com/#download), and [OpenSSL](https://www.openssl.org/source/). If you use a package manager, check against [BUILDING.md](https://github.com/monero-project/kovri/blob/master/BUILDING.md) for minimum version requirements. -1. Choose a port between ```9111``` and ```30777```. For this example, we'll use port ```12345```. **Please, do not use this number outside of this example as it will effect your anonymity**. -2. Open port ```12345``` in your NAT/Firewall to allow incoming TCP/UDP connections. -3. Clone, build, and run Kovri with one line: +1. Read [BUILDING.md](https://github.com/monero-project/kovri/blob/master/doc/BUILDING.md) and build instructions and minimum version requirements +1. Choose a port between ```9111``` and ```30777```. +2. Open your chosen port in your NAT/Firewall to allow incoming TCP/UDP connections (or optional UPnP, see [BUILDING.md](https://github.com/monero-project/kovri/blob/master/doc/BUILDING.md)) +3. Clone, build, and run Kovri. **Replace port ```12345``` with your chosen port**: ```bash -$ git clone https://github.com/monero-project/kovri && cd kovri/build && cmake ../ && make && ./kovri -p 12345 +$ git clone https://github.com/monero-project/kovri +$ cd kovri/build && cmake ../ && make +$ ./kovri -p 12345 ``` -## Build. Contribute. Ask questions! -- See [BUILDING.md](https://github.com/monero-project/kovri/blob/master/doc/BUILDING.md) for more options and instructions for your favourite OS. -- See [CONTRIBUTING.md](https://github.com/monero-project/kovri/blob/master/doc/CONTRIBUTING.md) and send us a PR. All developers welcome! +## Developers +- See [CONTRIBUTING.md](https://github.com/monero-project/kovri/blob/master/doc/CONTRIBUTING.md) before sending PR. + +## Documentation - See [FAQ.md](https://github.com/monero-project/kovri/blob/master/doc/FAQ.md) or join us in ```#kovri``` or ```#kovri-dev``` on Irc2P or Freenode. -- All documentation is on our ./doc directory +- All other documentation is on our ./doc directory ## Vulnerability Response - Please, submit a report via [HackerOne](https://hackerone.com/kovri) diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 975ceb9d..bab1e26b 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -1,3 +1,25 @@ +# Contributing + +## Workflow +To contribute a patch, please execute the following: + +1. Fork Kovri +2. Read [STYLE.md](https://github.com/monero-project/kovri/blob/master/doc/STYLE.md) +3. Create a topic branch +4. [**Sign**](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) your commit(s) +5. PR to branch ```development``` + + - In general, commits should be [atomic](https://en.wikipedia.org/wiki/Atomic_commit#Atomic_commit_convention) and diffs should be easy to read. For this reason, please try to not mix formatting fixes with non-formatting commits. + - Commit messages should be verbose by default, consisting of a short subject line (50 chars max), a blank line, and detailed explanatory text as separate paragraph(s) - unless the title alone is self-explanatory. + - If a particular commit references another issue, please add a reference. For example "See #123", or "Fixes #123". This will help us resolve tickets when we merge into ```master```. + - The body of the pull request should contain an accurate description of what the patch does and provide justification/reasoning for the patch (when appropriate). You should include references to any discussions such as other tickets or chats on IRC. + +## TODO's +- Do a quick search in the codebase for ```TODO(unassigned):``` and/or pick a ticket and start patching! +- If you create a TODO, assign it to yourself or write in ```TODO(unassigned):``` + +# Code of Conduct (22/C4.1) + ## License Copyright (c) 2009-2015 Pieter Hintjens. @@ -106,3 +128,26 @@ C4 is meant to provide a reusable optimal collaboration model for open source so - A new Contributor who makes a correct patch SHALL be invited to become a Maintainer. - Administrators MAY remove Maintainers who are inactive for an extended period of time, or who repeatedly fail to apply this process accurately. - Administrators SHOULD block or ban "bad actors" who cause stress and pain to others in the project. This should be done after public discussion, with a chance for all parties to speak. A bad actor is someone who repeatedly ignores the rules and culture of the project, who is needlessly argumentative or hostile, or who is offensive, and who is unable to self-correct their behavior when asked to do so by others. + +# Conflict resolution +``` +2015-11-30 18:37:36 &anonimal Ok, so let's determine a pecking order re: conflict resolution: +2015-11-30 18:37:40 &anonimal Scenario: +2015-11-30 18:38:18 &anonimal 1. Contributor has an idea and it should be master +2015-11-30 18:38:38 &anonimal 2. 'lead dev' disagrees with idea, wants their own version of idea in master +2015-11-30 18:39:11 &anonimal 3. Monero likes contributor's idea, but lead dev has more experience with the code. +2015-11-30 18:39:16 ~fluffypon ok so this is something that we *have* established in Monero +2015-11-30 18:39:16 &anonimal What is the solution? +2015-11-30 18:39:44 ~fluffypon we basically open decisions up to the community, and try get so-called "rough consensus" +2015-11-30 18:40:23 ~fluffypon there are plenty of savvy community members who aren't direct contributors to the codebase, so opening it up for discussion is good +2015-11-30 18:40:45 ~fluffypon if it is truly contentious and there's no general community consensus then we escalate it +2015-11-30 18:41:05 ~fluffypon basically the Monero Core Team have an online meeting +2015-11-30 18:41:08 ~fluffypon which is closed to outside participants, but publicly visible +2015-11-30 18:41:19 ~fluffypon and we discuss the options, and then vote on it +2015-11-30 18:41:26 &anonimal Is there a timelimit to gather this consensus? How long should devs wait for results? +2015-11-30 18:41:55 ~fluffypon every core team member has the option of a veto vote, else they must vote no, yes but I can't support the effort, yes and I can support the effort, yes and I can drive the effort +2015-11-30 18:42:09 ~fluffypon anonimal: it depends on the urgency of the situation +2015-11-30 18:42:15 ~fluffypon a nice-to-have feature might require a month of discussion +2015-11-30 18:42:25 ~fluffypon an urgent, but controversial, change might require a week +2015-11-30 18:42:54 &anonimal Ok, great to know. Thanks for clarifying. +``` diff --git a/doc/FAQ.md b/doc/FAQ.md index 23e92d92..7036d7fd 100644 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -3,16 +3,18 @@ ## What is Kovri? Kovri is a secure, private, untraceable C++ router implementation of the [I2P](https://geti2p.net) anonymous network. It was originally forked from i2pd. +## When is your first release? +Once essential QA has been resolved and I2CP is implemented, we will bring-forth a beta release. + ## What are the biggest differences between Kovri and i2pd? As we are currently in pre-alpha, we are working on following: - We provide both end-users and developers a [quality assurance](https://github.com/monero-project/kovri/issues/58) and [development model](https://github.com/monero-project/kovri/blob/master/doc/CONTRIBUTING.md) in order to provide better software for everyone. - We focus on implementing an [I2CP](https://geti2p.net/en/docs/spec/i2cp) server for any application to connect to and use the I2P network; this includes Monero. - We focus on creating a ["secure by default"](http://www.openbsd.org/security.html), easily maintainable, more-likely-to-be-reviewed I2P router. This will come with the cost of dropping lesser-used features found in the other routers, but core functionality and I2CP will be fully intact. By creating a smaller, efficient, "bare-bones" router, we will provide developers and researchers more time for security auditing and more time to question the I2P design and specifications. +- We will provide a Forum Funding System for features/development and vulnerability disclosures. - We will implement alternative reseeding options so users can use [Pluggable Transports](https://www.torproject.org/docs/pluggable-transports.html.en) instead of HTTPS for reseed. - We will implement extended functionality *(hidden mode + disabled inbound)* to provide anonymity for those who live in countries with extreme conditions or those firewalled by carrier-grade NAT or DS-Lite. -- We will provide bounty for vulnerability disclosures. -- We will provide bounty for features/development. - We will always create a welcome environment for collaboration. - We will always listen to your feedback and do our best to improve Kovri! @@ -37,12 +39,6 @@ Along came anonimal who, not wanting to see everyone's work to go to waste, revi Seeing that this sort of behavior would only hurt the I2P network, the remaining developers had [several important meetings](https://github.com/monero-project/kovri/issues/47) and Kovri was born. -## I found a bug or vulnerability. What do I do? -See our [CONTRIBUTING.md](https://github.com/monero-project/kovri/blob/master/doc/CONTRIBUTING.md) guide for bugs. +## I found a vulnerability and/or bug. What do I do? See our [README.md](https://github.com/monero-project/kovri/blob/master/doc/README.md) for reporting vulnerabilities. - -## What is your development cycle? -As we are in the midst of triage, we haven't fine-tuned our strategy. Given our presently available human-power, we do our best to provide (at the very least) an open collaboration model - though we aim to adhere to our present [development model](https://github.com/monero-project/kovri/blob/master/doc/CONTRIBUTING.md). - -## When is your first release? -Our release cycle has not yet been defined. Once I2CP is implemented and essential QA has been resolved, we will bring-forth a beta release. +See our [CONTRIBUTING.md](https://github.com/monero-project/kovri/blob/master/doc/CONTRIBUTING.md) guide for bugs. diff --git a/doc/STYLE.md b/doc/STYLE.md index 6d435c49..1fd9eede 100644 --- a/doc/STYLE.md +++ b/doc/STYLE.md @@ -1,10 +1,3 @@ -# Contributing -- Firstly, please read our [CONTRIBUTING.md](https://github.com/monero-project/kovri/blob/master/doc/CONTRIBUTING.md) guide -- Every pull request and correspondence will be treated with the utmost respect and consideration. - -## IRC -Join us in ```#kovri-dev``` on Irc2P or Freenode; we'll be happy to say hi! - ## Style We ardently adhere to (or are in the process of adhering to) [Google's C++ Style Guide](https://google.github.io/styleguide/cppguide.html). Please run [cpplint](https://github.com/google/styleguide/tree/gh-pages/cpplint) on any applicable work before contributing to Kovri and take no offense if your contribution ends up being style refactored. @@ -69,52 +62,3 @@ if (clearText[BUILD_REQUEST_RECORD_FLAG_OFFSET] & 0x40) { clearText + BUILD_REQUEST_RECORD_SEND_MSG_ID_OFFSET)))); } ``` - -## TODO's -- Do a quick search in the codebase for ```TODO(unassigned):``` and/or pick a ticket and start patching! -- If you create a TODO, assign it to yourself or write in ```TODO(unassigned):``` - -## Workflow -To contribute a patch, consider the following: - -- Fork Kovri -- Create a topic branch -- Commit and [**sign**](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) your feature(s)/patch(es) -- Pull request to branch ```development``` - -In general, commits should be [atomic](https://en.wikipedia.org/wiki/Atomic_commit#Atomic_commit_convention) and diffs should be easy to read. For this reason, please try to not mix formatting fixes with non-formatting commits. - -Commit messages should be verbose by default, consisting of a short subject line (50 chars max), a blank line, and detailed explanatory text as separate paragraph(s) - unless the title alone is self-explanatory. - -If a particular commit references another issue, please add a reference. For example "See #123", or "Fixes #123". This will help us resolve tickets when we merge into ```master```. - -The body of the pull request should contain an accurate description of what the patch does and provide justification/reasoning for the patch (when appropriate). You should include references to any discussions such as other tickets or chats on IRC. - -## Bounty -In the future we will provide bounty for vulnerabilities and bugs. Please stay tuned while we work out the details. - -## Model -We do our best to adhere to the [Agile](https://en.wikipedia.org/wiki/Agile_development)/[Scrum](https://en.wikipedia.org/wiki/Scrum_%28development%29) software development model. The benefits of such a model will become more apparent when our software and developer-base grows (we hope!). Please, consider this model before contributing. - -## Conflict resolution -``` -2015-11-30 18:37:36 &anonimal Ok, so let's determine a pecking order re: conflict resolution: -2015-11-30 18:37:40 &anonimal Scenario: -2015-11-30 18:38:18 &anonimal 1. Contributor has an idea and it should be master -2015-11-30 18:38:38 &anonimal 2. 'lead dev' disagrees with idea, wants their own version of idea in master -2015-11-30 18:39:11 &anonimal 3. Monero likes contributor's idea, but lead dev has more experience with the code. -2015-11-30 18:39:16 ~fluffypon ok so this is something that we *have* established in Monero -2015-11-30 18:39:16 &anonimal What is the solution? -2015-11-30 18:39:44 ~fluffypon we basically open decisions up to the community, and try get so-called "rough consensus" -2015-11-30 18:40:23 ~fluffypon there are plenty of savvy community members who aren't direct contributors to the codebase, so opening it up for discussion is good -2015-11-30 18:40:45 ~fluffypon if it is truly contentious and there's no general community consensus then we escalate it -2015-11-30 18:41:05 ~fluffypon basically the Monero Core Team have an online meeting -2015-11-30 18:41:08 ~fluffypon which is closed to outside participants, but publicly visible -2015-11-30 18:41:19 ~fluffypon and we discuss the options, and then vote on it -2015-11-30 18:41:26 &anonimal Is there a timelimit to gather this consensus? How long should devs wait for results? -2015-11-30 18:41:55 ~fluffypon every core team member has the option of a veto vote, else they must vote no, yes but I can't support the effort, yes and I can support the effort, yes and I can drive the effort -2015-11-30 18:42:09 ~fluffypon anonimal: it depends on the urgency of the situation -2015-11-30 18:42:15 ~fluffypon a nice-to-have feature might require a month of discussion -2015-11-30 18:42:25 ~fluffypon an urgent, but controversial, change might require a week -2015-11-30 18:42:54 &anonimal Ok, great to know. Thanks for clarifying. -```