README makeover

This readme is now appropriate to include in release tarballs.

README.md

@@ -3,42 +3,111 @@
 A general-purpose programming language and toolchain for maintaining
 **robust**, **optimal**, and **reusable** software.
 
-## Resources
+https://ziglang.org/
 
- * [Introduction](https://ziglang.org/learn/#introduction)
+## Documentation
- * [Download & Documentation](https://ziglang.org/download)
+
- * [Chapter 0 - Getting Started | ZigLearn.org](https://ziglearn.org/)
+If you are looking at this README file in a source tree, please refer to the
- * [Community](https://github.com/ziglang/zig/wiki/Community)
+**Release Notes**, **Language Reference**, or **Standard Library
- * [Contributing](https://github.com/ziglang/zig/blob/master/.github/CONTRIBUTING.md)
+Documentation** corresponding to the version of Zig that you are using by
- * [Code of Conduct](https://github.com/ziglang/zig/blob/master/.github/CODE_OF_CONDUCT.md)
+following the appropriate link on the
- * [Frequently Asked Questions](https://github.com/ziglang/zig/wiki/FAQ)
+[download page](https://ziglang.org/download).
- * [Community Projects](https://github.com/ziglang/zig/wiki/Community-Projects)
+
+Otherwise, you're looking at a release of Zig, and you can find documentation
+here:
+
+ * doc/langref.html
+ * doc/std/index.html
 
 ## Installation
 
  * [download a pre-built binary](https://ziglang.org/download/)
  * [install from a package manager](https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager)
- * [build from source](https://github.com/ziglang/zig/wiki/Building-Zig-From-Source)
  * [bootstrap zig for any target](https://github.com/ziglang/zig-bootstrap)
 
-## License
+A Zig installation is composed of two things:
 
-The ultimate goal of the Zig project is to serve users. As a first-order
+1. The Zig executable
-effect, this means users of the compiler, helping programmers to write better
+2. The lib/ directory
-software. Even more important, however, are the end-users.
 
-Zig is intended to be used to help **end-users** accomplish their goals. Zig
+At runtime, the executable searches up the file system for the lib/ directory,
-should be used to empower end-users, never to exploit them financially, or to
+relative to itself:
-limit their freedom to interact with hardware or software in any way.
 
-However, such problems are best solved with social norms, not with software
+* lib/
-licenses. Any attempt to complicate the software license of Zig would risk
+* zig/lib/
-compromising the value Zig provides.
+* ../lib/
+* ../zig/lib/
+* (and so on)
 
-Therefore, Zig is available under the MIT (Expat) License, and comes with a
+In other words, you can **unpack a release of Zig anywhere**, and then begin
-humble request: use it to make software better serve the needs of end-users.
+using it immediately. There is no need to install it globally, although this
+mechanism supports that use case too (i.e. `/usr/bin/zig` and `/usr/lib/zig/`).
 
-This project redistributes code from other projects, some of which have other
+## Building from Source
-licenses besides MIT. Such licenses are generally similar to the MIT license
+
-for practical purposes. See the subdirectories and files inside lib/ for more
+Ensure you have the required dependencies:
-details.
+
+ * CMake >= 2.8.12
+ * System C/C++ Toolchain
+ * LLVM, Clang, LLD development libraries == 16.x
+
+Then it is the standard CMake build process:
+
+```
+mkdir build
+cd build
+cmake ..
+make install
+```
+
+For more options, tips, and troubleshooting, please see the
+[Building Zig From Source](https://github.com/ziglang/zig/wiki/Building-Zig-From-Source)
+page on the wiki.
+
+## Contributing
+
+Zig is Free and Open Source Software. We welcome bug reports and patches from
+everyone. However, keep in mind that Zig governance is BDFN (Benevolent
+Dictator For Now) which means that Andrew Kelley has final say on the design
+and implementation of everything.
+
+One of the best ways you can contribute to Zig is to start using it for an
+open-source personal project.
+
+This leads to discovering bugs and helps flesh out use cases, which lead to
+further design iterations of Zig. Importantly, each issue found this way comes
+with real world motivations, making it straightforward to explain the reasoning
+behind proposals and feature requests.
+
+You will be taken much more seriously on the issue tracker if you have a
+personal project that uses Zig.
+
+The issue label
+[Contributor Friendly](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3A%22contributor+friendly%22)
+exists to help you find issues that are **limited in scope and/or knowledge of
+Zig internals.**
+
+Please note that issues labeled
+[Proposal](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aproposal)
+but do not also have the
+[Accepted](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted)
+label are still under consideration, and efforts to implement such a proposal
+have a high risk of being wasted. If you are interested in a proposal which is
+still under consideration, please express your interest in the issue tracker,
+providing extra insights and considerations that others have not yet expressed.
+The most highly regarded argument in such a discussion is a real world use case.
+
+For more tips, please see the
+[Contributing](https://github.com/ziglang/zig/wiki/Contributing) page on the
+wiki.
+
+## Community
+
+The Zig community is decentralized. Anyone is free to start and maintain their
+own space for Zig users to gather. There is no concept of "official" or
+"unofficial". Each gathering place has its own moderators and rules. Users are
+encouraged to be aware of the social structures of the spaces they inhabit, and
+work purposefully to facilitate spaces that align with their values.
+
+Please see the [Community](https://github.com/ziglang/zig/wiki/Community) wiki
+page for a public listing of social spaces.