Consolidate in-repo documentation (#3143)

* move doc/misc to top level, add READMEs

* Move docs -> doc/devel

This also consolidates the _three_ documents describing (differently)
how to build Taskwarrior into a signle document.

doc/devel/contrib/README.md

@@ -0,0 +1,7 @@
+# Contributing To Taskwarrior
+
+ * [Welcome, Open Source Contributor](first_time.md)
+ * [Developing Taskwarrior](development.md)
+ * [Coding Style](coding_style.md)
+ * [Branching Model](branching.md)
+ * [Rust and C++](rust-and-c++.md)

doc/devel/contrib/branching.md

@@ -0,0 +1,13 @@
+Software development typically requires a standardized branching model, to manage complexity and parallel efforts.
+The branching model can be a source of confusion for developers, so this document describes how branching is used.
+
+We use the following branching model:
+
+* `develop` is the current development branch. All work is done here, and upon
+  release it will be branched to a release branch. While `develop` is not
+  stable, we utilize CI to ensure we're at least not merging improvements that
+  break existing tests, and hence should be relatively safe. We still recommend
+  making backups when using the development branch.
+
+* The most recent minor release is in a branch named after the release, e.g., `2.7.0`.
+  This branch is used for bug-fixes of the latest release.

doc/devel/contrib/coding_style.md

@@ -0,0 +1,31 @@
+# Coding Style
+
+The coding style used for the Taskwarrior, Taskserver, and other codebases is deliberately kept simple and a little vague.
+This is because there are many languages involved (C++, C, Python, sh, bash, HTML, troff and more), and specіfying those would be a major effort that detracts from the main focus which is improving the software.
+
+Instead, the general guideline is simply this:
+
+Make all changes and additions such that they blend in perfectly with the surrounding code, so it looks like only one person worked on the source, and that person is rigidly consistent.
+
+To be a little more explicit:
+
+## C++
+
+-   All functionality in C++17 is allowed.
+
+-   Indent C++ code using two spaces, no tabs
+
+-   Surround operators and expression terms with a space.
+    This includes a space between a function name and its list of arguments.
+
+-   No cuddled braces
+
+-   Class names are capitalized, variable names are not
+
+## Python
+
+Follow [PEP8](https://www.python.org/dev/peps/pep-0008/) as much as possible.
+
+## Rust
+
+Rust code should be formatted with `rustfmt` and generally follow Rust style guidelines.

doc/devel/contrib/development.md

@@ -0,0 +1,48 @@
+# Developing Taskwarrior
+
+## Satisfy the Requirements:
+
+ * CMake 3.0 or later
+ * gcc 7.0 or later, clang 6.0 or later, or a compiler with full C++17 support
+ * libuuid (if not on macOS)
+ * python 3 (optional, for running the test suite)
+ * Rust 1.64.0 or higher (hint: use https://rustup.rs/ instead of using your system's package manager)
+
+## Obtain and Build Code:
+```
+    $ git clone --recursive https://github.com/GothenburgBitFactory/taskwarrior taskwarrior.git
+    $ cd taskwarrior.git
+    $ git checkout develop               # Latest dev branch
+    $ git submodule init                 # This is now done by cmake as a test
+    $ git submodule update               # Update the libhsared.git submodule
+    $ cmake -DCMAKE_BUILD_TYPE=debug .   # debug or release. Default: neither
+    $ make VERBOSE=1 -j4                 # Shows details, builds using 4 jobs
+                                         # Alternately 'export MAKEFLAGS=-j 4'
+```
+
+This will build several executables, but the one you want is probably `src/task`.
+When you make changes, just run the last line again.
+
+## Run the Test Suite:
+
+First switch to the test directory:
+
+```
+    $ cd test
+```
+Then you can run all tests, showing details, with
+```
+    $ make VERBOSE=1
+```
+Alternately, run the tests with the details hidden in `all.log`:
+```
+    $ ./run_all
+```
+Either way, you can get a summary of any test failures with:
+```
+    $ ./problems
+```
+
+Note that any development should be performed using a git clone, and the current development branch.
+The source tarballs do not reflect HEAD, and do not contain the test suite.
+Follow the [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) for creating a pull request.

doc/devel/contrib/first_time.md

@@ -0,0 +1,68 @@
+# Welcome, Open Source Contributor
+
+Welcome, potential new Open Source contributor! This is a guide to show you exactly how to make a contribution, and will lead you through the entire process.
+
+There are many people who wish to start contributing, but don't know how or where to start.
+If this might be the case for you, then please read on, this guide is for you.
+Because we want you to join in the fun with Open Source - it can be fun and rewarding, improve your skills, or just give you a way to contribute back to a project.
+
+## How to Help
+
+Help is needed in all areas of Taskwarrior development - design, coding, testing, support and marketing.
+Applicants must be friendly.
+Perhaps you are looking to help, but don't know where to start.
+Perhaps you have skills we are looking for, here are ways you may be able to help:
+
+-   Use Taskwarrior, become familiar with it, and make suggestions.
+    We get great feedback from both new users and veteran users.
+    New users have a fresh approach that we can no longer achieve, while veteran users develop clever and crafty ways to use the product.
+
+-   Report bugs and odd behavior when you see it.
+    We don't necessarily know it's broken, unless you tell us.
+
+-   Suggest enhancements.
+    We get lots of these, and it's great.
+    Some really good ideas have been suggested and implemented.
+    Sure, some are out of scope, or plain crazy, but the stream of suggestions is fascinating to think about.
+
+-   Participate in the [bug tracking](https://github.com/GothenburgBitFactory/taskwarrior/issues) database, to help others and maybe learn something yourself.
+
+-   Proofread the documentation and man pages.
+
+-   Improve the documentation.
+
+-   Improve the man pages.
+
+-   Help improve the tutorials.
+    Make your own tutorial.
+
+-   Confirm a bug.
+    Nothing gets fixed without confirmation.
+
+-   Refine a bug.
+    Provide relevant details, elaborate on the behavior.
+
+-   Fix a bug.
+    Send a patch.
+    For this you'll need to know some C++ or Rust, and understand the [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow).
+    See [Developing Taskwarrior](./development.md) for more information.
+    We welcome all bug fixes, provided the work is done well and doesn't create other problems or introduce new dependencies.
+    We recommend talking to us before starting: we are happy to help you out!
+
+-   Write a unit test.
+    Unit tests are possibly the most useful contributions of all, because they not only improve the quality of the code, but prevent future regressions, therefore maintaining quality of subsequent releases.
+    Plus, broken tests are a great motivator for us to fix the causal defect.
+    You'll need Python skills.
+
+-   Spread the word.
+    Help others become more effective at managing tasks.
+    Share your methodology, to inspire others.
+
+-   Encouragement.
+    Tell us what works for you, and what doesn't.
+    It's all good.
+
+-   Donate! Help offset costs.
+
+Please remember that we need contributions from all skillsets, however small.
+Every contribution helps.

doc/devel/contrib/rust-and-c++.md

@@ -0,0 +1,29 @@
+# Rust and C++
+
+Taskwarrior has historically been a C++ project, but as part of an [ongoing effort to replace its storage backend](https://github.com/GothenburgBitFactory/taskwarrior/issues/2770) it now includes a Rust library called TaskChampion.
+To develop Taskwarrior, you will need both a [C++ compiler and tools](./development.md), and a [Rust toolchain](https://www.rust-lang.org/tools/install).
+However, most tasks will only require you to be familiar with one of the two languages.
+
+## TaskChampion
+
+TaskChampion implements storage and access to "replicas" containing a user's tasks.
+It defines an abstract model for this data, and also provides a simple Rust API for manipulating replicas.
+It also defines a method of synchronizing replicas and provides an implementation of that method in the form of a sync server.
+TaskChampion provides a C interface via the `taskchampion-lib` crate.
+
+Other applications, besides Taskwarrior, can use TaskChampion to manage tasks.
+Applications written in Rust can use the `taskchampion` crate, while those in other languages may use the `taskchampion-lib` crate.
+Taskwarrior is just one application using the TaskChampion interface.
+
+You can build Taskchampion locally by simply running `cargo build` in the root of this repository.
+The implementation, including more documentation, is in the [`rust`](../../rust) subdirectory.
+
+## Taskwarrior's use of TaskChampion
+
+Taskwarrior's interface to TaskChampion has a few layers:
+
+* The skeletal Rust crate in [`src/tc/rust`](../../src/tc/rust) brings the symbols from `taskchampion-lib` under CMake's management.
+  The corresponding header file is included from [`taskchampion/lib`](../../taskchampion/lib).
+  All of these symbols are placed in the C++ namespace, `tc::ffi`.
+* C++ wrappers for the types from `taskchampion-lib` are defined in [`src/tc`](../../src/tc), ensuring memory safety (with `unique_ptr`) and adding methods corresponding to the Rust API's methods.
+  The wrapper types are in the C++ namespace, `tc`.