Core Development and Living Whitepaper consolidation

docs/core-development/code-standards.md

@@ -0,0 +1,47 @@
+title: Code Standards
+description: Learn about the code standards expected when contributing to the nano protocol and node implementation
+
+# Code standards
+
+## Formatting
+
+clang-format is used to enforce most of the formatting rules, such as:
+
+* Tabs for indentation.
+* Open braces go on new lines.
+* Space before open parenthesis.
+* Space after comma.
+
+Running `ci/clang-format-all.sh` on \*nix systems is required before pushing your code to ensure that the formatting is good. If you want to do formatting from the IDE, chances are there's a plugin available. Visual studio for instance provides a way to automatically format on saving. The definition file `.clang-format` is located in the project root directory.
+
+Make sure you set up your editor to use tabs. Use tabs for indentation, and spaces for alignment [^1]. That way, you can use any tab size you want in your favorite editor, but the code will still look good for people with different settings.
+
+## General guidelines
+
+* Use `auto` type inference for local variables if it's clear from the context what the type will be. Use your best judgement, sometimes adding explicit types can increase readability [^2]
+* Handle exceptions, including IO exceptions for file and network operations.
+* Be liberal with `debug_assert`. Use asserts to check invariants, not potential runtime errors, which should be handled gracefully. `debug_assert` has an advantage over normal `assert` as it will always print out the stacktrace of the current thread when it hits. Debug asserts are for detecting bugs, not error handling. There is also `release_assert` which is similar to `debug_assert` but also hits in a release build. When there is unexpected behaviour and no suitable way to recover it can be used to halt program execution.
+* Be liberal with `logger.always_log` or `logger.try_log` statements, except in performance critical paths.
+* Add comments to explain complex and subtle situations, but avoid comments that reiterates what the code already says.
+* Use RAII and C++11 smart pointers to manage memory and other resources.
+
+## Performance and scalabiliy considerations
+
+* When making changes, think about performance and scalability. Pick good data structures and think about algorithmic complexity. 
+    * For small data sets, `std::vector` should be your to-go container, as a linear scan through contiguous memory is often faster than any alternative due to memory being read in cache lines.
+    * Nested loops yield quadratic behavior - is there an alternative? A typical example is removing an inner lookup loop with an unordered set/map to improve lookup performance to O(1).
+* Make sure your change doesn't conflict with the scalability characteristics described in the white paper.
+
+## Security
+
+Your code will be reviewed with security in mind, but please do your part before creating a pull request:
+
+* Familiarize yourself with best practices for writing secure C++ code. In particular:
+    * Consult https://wiki.sei.cmu.edu/confluence/display/cplusplus
+    * Avoid using ANSI C functions. Many of these are prone to buffer overruns.
+    * Avoid using C strings and direct buffer manipulation.
+
+* Use static and dynamic analysis tools, such as valgrind, XCode instrumentation, linters and sanitizers. These tools are also great for debugging crashes and performance problems.
+
+[^1]: https://dmitryfrank.com/articles/indent_with_tabs_align_with_spaces
+[^2]: http://www.acodersjourney.com/2016/02/c-11-auto/

docs/core-development/collaboration-process.md

@@ -0,0 +1,86 @@
+title: Collaboration Process
+description: Find out how the open source collaboration process works with the nano protocol and node software
+
+# Collaboration Process
+
+## Code Process
+
+**Fork and do all your work on a branch**
+
+Nano prefers the standard GitHub workflow. You create a fork of the nanocurrency/nano-node repository (or other repositories as needed), make changes on new branches for features/fixes, and push these up to be added as Pull Requests. 
+
+**Create pull requests**
+
+Before:
+
+* Branch out of the **develop** branch. The **master** branch is only updated on new releases.
+* Review your code locally. Have you followed the [Code Standards](code-standards.md) closely?
+* Run tests: `core_test`,`qt_test`,`rpc_test` (see [running tests](understanding-the-code.md#tests) for more details). Did you consider adding a test case for your feature?
+* Run ASAN, TSAN and Valgrind to detect memory, threading or other bugs
+* Commit and push your fork branch
+
+After:
+
+* Create pull request on the upstream repository:
+    * Make sure you add a description that clearly describes the purpose of the PR.
+    * If the PR solves one or more issues, please reference these in the description.
+* Check that CI completes successfully - this can take up to a few hours depending on current CI queues. If any failures exist, fix the problem and push an update.
+* Respond to comments and reviews in a timely fashion.
+
+**Resolve conflicts**
+
+If time passes between your pull request (PR) submission and the team accepting it, merge conflicts may occur due to activity on develop, such as merging other PR's before yours. In order for your PR to be accepted, you must resolve these conflicts.
+
+The preferred process is to rebase your changes, resolve any conflicts, and push your changes again. [^1][^2]
+
+* Check out your branch
+* `git fetch upstream`
+* `git rebase upstream/develop`
+* Resolve conflicts in your favorite editor
+* `git add {filename}`
+* `git rebase --continue`
+* Commit and push your branch
+
+**Consider squashing or amending commits**
+
+In the review process, you're likely to get feedback. You'll commit and push more changes, get more feedback, etc. 
+
+This can lead to a messy git history, and can make stuff like bisecting harder.
+
+Once your PR is OK'ed, please squash the commits into a one.[^3]
+
+Note that you can also update the last commit with `git commit --amend`. Say your last commit had a typo. Instead of committing and having to squash it later, simply commit with amend and push the branch.
+
+## Finding issues or features to work on
+
+- Issues are available on GitHub, with the most urgent being in the latest milestone for release
+- Start with issues labeled as [`good first issue`](https://github.com/nanocurrency/nano-node/labels/good%20first%20issue) or connect with the NF core developers on [Discord](https://chat.nano.org) or the [forum](https://forum.nano.org) for ideas on how to help
+- If you find an issue you'd like to help with, comment and tag a [Nano Foundation team member](https://github.com/orgs/nanocurrency/people) who can evaluate and assign it to you
+
+## Submitting issues and feature requests
+
+Standard GitHub templates exist for submitting any found issues or feature requests. If you plan on working on a bug or feature that doesn't already have a GitHub Issue associated with it, please submit it first so the team is aware. See https://github.com/nanocurrency/nano-node/issues/new/choose for templates.
+
+## Discussion channels
+
+Various channels exist for discussing code changes with the Nano Foundation and community.
+
+**GitHub**
+
+To help persist useful information about a particular issue or feature, it is best to discuss within the related GitHub Issue or Pull Request. Members of the nano community and Nano Foundation actively follow and will engage when available.
+
+**Discord for chat**
+
+For live chat, join the server at https://chat.nano.org and check out the `#protocol` and `#development` channels. The various channels under the `TESTING` section can also be helpful to follow.
+
+**Forum**
+
+Another area for technical and code related discussions is the [forum](https://forum.nano.org). There are categories for `Protocol Design` and `Development` that are useful in discussing ideas. This can be a great place for getting feedback on ideas and exploring further before finalizing fixes and features in GitHub.
+
+## Proposals
+
+There currently is no formal process for proposals on the nano network. This is an area actively being investigated and if requirements for submissions change, this area will be updated. For now, if you wish to propose an new idea, it is recommended to discuss on the [forum](https://forum.nano.org) first to gather feedback and use the [GitHub Issues](https://github.com/nanocurrency/nano-node/issues/new/choose) on the concept is solidifed/validated.
+
+[^1]: https://help.github.com/articles/resolving-merge-conflicts-after-a-git-rebase/
+[^2]: https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/
+[^3]: https://github.com/todotxt/todo.txt-android/wiki/Squash-All-Commits-Related-to-a-Single-Issue-into-a-Single-Commit

docs/core-development/overview.md

@@ -0,0 +1,41 @@
+title: Core Development Overview
+description: All you need to know to help contribute to the core development of the nano node and protocol
+
+# Core Development
+
+Welcome and thanks for your interest in core development of the nano! The following resources contain information and guides for getting involved with the development of the node and protocol.
+
+## Getting started
+
+It is recommended to have an understanding of how the nano protocol is designed to work so the code can be more easily read and evaluated.
+
+- Start by reviewing the [living whitepaper](../living-whitepaper/index.md)
+- Read through (or try out) the [running a node guides](../running-a-node/overview.md)
+- Understand [the basics](../integration-guides/the-basics.md) and maybe even some [advanced details](../integration-guides/advanced.md) about integrations
+- Learn how to [build the node yourself](../integration-guides/build-options.md)
+- Participate in the community through [Discord](https://chat.nano.org) and the [Forum](https://forum.nano.org)
+- Start perusing the code in the repositories below and don't be afraid to ask questions
+
+
+## Code repositories
+
+The Nano Foundation manages the [`nanocurrency`](https://github.com/nanocurrency) GitHub Organization account which includes various repositories for nano tools and implementations. Below is a partial list of the most common repositories referenced.
+
+| Name | Language | Purpose |
+|------|----------|---------|
+| [nanocurrency/nano-node](https://github.com/nanocurrency/nano-node) | C++| Primary node implementation used on the nano network |
+| [nanocurrency/nano-work-server](https://github.com/nanocurrency/nano-work-server) | Rust | Standalone server for generating work values for blocks |
+| [nanocurrency/protocol](https://github.com/nanocurrency/protocol) | Kaitai Struct | Specification for nano network message protocol |
+| [nanocurrency/nanodb-specification](https://github.com/nanocurrency/nanodb-specification) | Kaitai Struct | Specification for database tables and fields used by the `nano-node` implementation |
+| [nanocurrency/nano-docs](https://github.com/nanocurrency/nano-docs) | Markdown | MKDocs based documentation this docs.nano.org site is built from |
+
+Most of the content in the following documentation is focused around the [nanocurrency/nano-node](https://github.com/nanocurrency/nano-node) repository, as that is where most development activity occurs. But there are tons of related projects creating useful tools, libraries, services and more for the nano ecosystem (see some options in [GitHub](https://github.com/search?q=nanocurrency&type=discussions)).
+
+## Security vulnerability reporting
+
+--8<-- "security-vulnerability-reporting.md"
+
+
+## Nano Foundation core developers
+
+In addition to contributions from the wider nano community, the [Nano Foundation](https://nano.org/foundation) manages a team of core developers who contribute to the protocol and primary node implementation. For a list of code contributors, see the [GitHub Insights page](https://github.com/nanocurrency/nano-node/graphs/contributors).