Adding GitHub-styled README and CONTRIBUTING files in Markdown.

4 files changed, 274 insertions, 24 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..a7bc357b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,90 @@
+# Contributing Guidelines
+
+The following is a set of guidelines for contributing to NGINX Unit.  We do
+appreciate that you are considering contributing!
+
+## Table Of Contents
+
+- [Getting Started](#getting-started)
+- [Ask a Question](#ask-a-question)
+- [Contributing](#contributing)
+- [Git Style Guide](#git-style-guide)
+
+
+## Getting Started
+
+Check out the [Quick Installation](README.md#quick-installation) and
+[Howto](https://unit.nginx.org/howto/) guides to get NGINX Unit up and running.
+
+
+## Ask a Question
+
+Please open an [issue](https://github.com/nginx/unit/issues/new) on GitHub with
+the label `question`.  You can also ask a question on
+[Slack](https://nginxcommunity.slack.com) or the NGINX Unit mailing list,
+unit@nginx.org (subscribe
+[here](https://mailman.nginx.org/mailman3/lists/unit.nginx.org/)).
+
+
+## Contributing
+
+### Report a Bug
+
+Ensure the bug was not already reported by searching on GitHub under
+[Issues](https://github.com/nginx/unit/issues).
+
+If the bug is a potential security vulnerability, please report using our
+[security policy](https://unit.nginx.org/troubleshooting/#getting-support).
+
+To report a non-security bug, open an
+[issue](https://github.com/nginx/unit/issues/new) on GitHub with the label
+`bug`.  Be sure to include a title and clear description, as much relevant
+information as possible, and a code sample or an executable test case showing
+the expected behavior that doesn't occur.
+
+
+### Suggest an Enhancement
+
+To suggest an enhancement, open an
+[issue](https://github.com/nginx/unit/issues/new) on GitHub with the label
+`enhancement`.  Please do this before implementing a new feature to discuss the
+feature first.
+
+
+### Open a Pull Request
+
+Before submitting a PR, please read the NGINX Unit code guidelines to know more
+about coding conventions and benchmarks.  Fork the repo, create a branch, and
+submit a PR when your changes are tested and ready for review.  Again, if you'd
+like to implement a new feature, please consider creating a feature request
+issue first to start a discussion about the feature.
+
+
+## Git Style Guide
+
+- Keep a clean, concise and meaningful `git commit` history on your branch,
+  rebasing locally and squashing before submitting a PR
+
+- For any user-visible changes, updates, and bugfixes, add a note to
+  `docs/changes.xml` under the section for the upcoming release, using `<change
+  type="feature">` for new functionality, `<change type="change">` for changed
+  behavior, and `<change type="bugfix">` for bug fixes.
+
+- In the subject line, use the past tense ("Added feature", not "Add feature");
+  also, use past tense to describe past scenarios, and present tense for
+  current behavior
+
+- Limit the subject line to 67 characters, and the rest of the commit message
+  to 80 characters
+
+- Use subject line prefixes for commits that affect a specific portion of the
+  code; examples include "Tests:", "Packages:", or "Docker:", and also
+  individual languages such as "Java:" or "Ruby:"
+
+- Reference issues and PRs liberally after the subject line; if the commit
+  remedies a GitHub issue, [name
+  it](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)
+  accordingly
+
+- Don't rely on command-line commit messages with `-m`; use the editor instead
+
diff --git a/README b/README
deleted file mode 100644
index f0b84a42..00000000
--- a/README
+++ /dev/null
@@ -1,24 +0,0 @@
-
-NGINX Unit
-----------
-
-The documentation and binary packages are available online:
-
-  http://unit.nginx.org
-
-The source code is provided under the terms of Apache License 2.0:
-
-  http://hg.nginx.org/unit
-
-Please ask questions, report issues, and send patches to the mailing list:
-
-  unit@nginx.org (http://mailman.nginx.org/mailman/listinfo/unit)
-
-or via Github:
-
-  https://github.com/nginx/unit
-
---
-NGINX, Inc.
-http://nginx.com
-
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..05bdbb91
--- /dev/null
+++ b/README.md
@@ -0,0 +1,184 @@
+# NGINX Unit
+
+## Universal Web App Server
+
+![NGINX Unit Logo](docs/unitlogo.png)
+
+NGINX Unit is a lightweight and versatile open-source server that has
+three core capabilities:
+
+- it is an HTTP reverse proxy,
+- a web server for static media assets,
+- and an application server that runs code in seven languages.
+
+We are building a universal tool that compresses several layers of the modern
+application stack into a potent, coherent solution with a focus on performance,
+low latency, and scalability. It is intended as a building block for any web
+architecture regardless of its complexity, from enterprise-scale deployments to
+your pet's homepage.
+
+Unit's native RESTful JSON API enables dynamic updates with zero interruptions
+and flexible configuration, while its out-of-the-box productivity reliably
+scales to production-grade workloads. We achieve that with a complex,
+asynchronous, multithreading architecture comprising multiple processes to
+ensure security and robustness while getting the most out of today's computing
+platforms.
+
+
+## Quick Installation
+
+### macOS
+
+``` console
+$ brew install nginx/unit/unit
+```
+
+For details and available language packages, see the
+[docs](https://unit.nginx.org/installation/#homebrew).
+
+
+### Docker
+
+``` console
+$ docker pull docker.io/nginx/unit
+```
+
+For a description of image tags, see the
+[docs](https://unit.nginx.org/installation/#docker-images).
+
+
+### Amazon Linux, Fedora, RedHat
+
+``` console
+$ curl -sL 'https://unit.nginx.org/_downloads/setup-unit.sh' | sudo -E bash
+# yum install unit
+```
+
+For details and available language packages, see the
+[docs](https://unit.nginx.org/installation/#official-packages).
+
+
+### Debian, Ubuntu
+
+``` console
+$ curl -sL 'https://unit.nginx.org/_downloads/setup-unit.sh' | sudo -E bash
+
+# apt install unit
+```
+
+For details and available language packages, see the
+[docs](https://unit.nginx.org/installation/#official-packages).
+
+
+## Running a Hello World App
+
+Suppose you saved a PHP script as `/www/helloworld/index.php`:
+``` php
+<?php echo "Hello, PHP on Unit!"; ?>
+```
+
+To run it on Unit with the `unit-php` module installed, first set up an
+application object. Let's store our first config snippet in a file called
+`config.json`:
+
+``` json
+{
+    "helloworld": {
+        "type": "php",
+        "root": "/www/helloworld/"
+    }
+}
+```
+
+Saving it as a file isn't necessary, but can come in handy with larger objects.
+
+Now, `PUT` it into the `config/applications` section of Unit's control API,
+usually available by default via a Unix domain socket:
+
+``` console
+# curl -X PUT --data-binary @config.json --unix-socket  \
+       /path/to/control.unit.sock http://localhost/config/applications
+```
+``` json
+
+{
+	"success": "Reconfiguration done."
+}
+```
+
+Next, reference the app from a listener object in the `config/listeners`
+section of the API.  This time, we pass the config snippet straight from the
+command line:
+
+``` console
+# curl -X PUT -d '{"127.0.0.1:8000": {"pass": "applications/helloworld"}}'  \
+       --unix-socket /path/to/control.unit.sock http://localhost/config/listeners
+```
+``` json
+{
+    "success": "Reconfiguration done."
+}
+```
+
+Now Unit accepts requests at the specified IP and port, passing them to the
+application process. Your app works!
+
+``` console
+$ curl 127.0.0.1:8080
+
+      Hello, PHP on Unit!
+```
+
+Finally, query the entire `/config` section of the control API:
+
+``` console
+# curl --unix-socket /path/to/control.unit.sock http://localhost/config/
+```
+
+Unit's output should contain both snippets, neatly organized:
+
+``` json
+{
+    "listeners": {
+        "127.0.0.1:8080": {
+            "pass": "applications/helloworld"
+        }
+    },
+
+    "applications": {
+        "helloworld": {
+            "type": "php",
+            "root": "/www/helloworld/"
+        }
+    }
+}
+```
+
+For full details of configuration management, see the
+[docs](https://unit.nginx.org/configuration/#configuration-management).
+
+
+## Community
+
+- The go-to place to start asking questions and share your thoughts is
+  our [Slack channel](https://nginxcommunity.slack.com/).
+
+- Our [GitHub issues page](https://github.com/nginx/unit/issues) offers
+  space for a more technical discussion at your own pace.
+
+- The [project map](https://github.com/orgs/nginx/projects/1) on
+  GitHub sheds some light on our current work and plans for the future.
+
+- Our [official website](https://unit.nginx.org/) may provide answers
+  not easily found otherwise.
+
+- Get involved with the project by contributing! See the
+  [contributing guide](CONTRIBUTING.md) for details.
+
+- To reach the team directly, subscribe to the
+  [mailing list](https://mailman.nginx.org/mailman/listinfo/unit).
+
+- For security issues, [email us](security-alert@nginx.org), mentioning
+  NGINX Unit in the subject and following the [CVSS
+  v3.1](https://www.first.org/cvss/v3.1/specification-document) spec.
+
diff --git a/docs/unitlogo.png b/docs/unitlogo.png
new file mode 100644
index 00000000..dbd87fd8
--- /dev/null
+++ b/docs/unitlogo.png