Merge pull request #6 from icecrime/update_documents

Update documents

MAINTAINERS

@@ -0,0 +1,277 @@
+# Containerd project maintainers file
+#
+# This file describes who runs the containerd project and how.
+# This is a living document - if you see something out of date or missing,
+# speak up!
+#
+# It is structured to be consumable by both humans and programs.
+# To extract its contents programmatically, use any TOML-compliant
+# parser.
+
+[Rules]
+
+    [Rules.maintainers]
+
+        title = "What is a maintainer?"
+
+        text = """
+There are different types of maintainers, with different responsibilities, but
+all maintainers have 3 things in common:
+
+1) They share responsibility in the project's success.
+2) They have made a long-term, recurring time investment to improve the project.
+3) They spend that time doing whatever needs to be done, not necessarily what
+is the most interesting or fun.
+
+Maintainers are often under-appreciated, because their work is harder to appreciate.
+It's easy to appreciate a really cool and technically advanced feature. It's harder
+to appreciate the absence of bugs, the slow but steady improvement in stability,
+or the reliability of a release process. But those things distinguish a good
+project from a great one.
+"""
+
+    [Rules.adding-maintainers]
+
+        title = "How are maintainers added?"
+
+        text = """
+Maintainers are first and foremost contributors that have shown they are
+committed to the long term success of a project. Contributors wanting to become
+maintainers are expected to be deeply involved in contributing code, pull
+request review, and triage of issues in the project for more than three months.
+
+Just contributing does not make you a maintainer, it is about building trust
+with the current maintainers of the project and being a person that they can
+depend on and trust to make decisions in the best interest of the project.
+
+Periodically, the existing maintainers curate a list of contributors that have
+shown regular activity on the project over the prior months. From this list,
+maintainer candidates are selected and proposed on the maintainers mailing list.
+
+After a candidate has been announced on the maintainers mailing list, the
+existing maintainers are given five business days to discuss the candidate,
+raise objections and cast their vote. Candidates must be approved by the BDFL
+and at least 66% of the current maintainers by adding their vote on the mailing
+list. Only maintainers of the repository that the candidate is proposed for are
+allowed to vote. The BDFL's vote is mandatory.
+
+If a candidate is approved, a maintainer will contact the candidate to invite
+the candidate to open a pull request that adds the contributor to the
+MAINTAINERS file. The candidate becomes a maintainer once the pull request is
+merged.
+"""
+
+    [Rules.stepping-down-policy]
+
+        title = "Stepping down policy"
+
+        text = """
+Life priorities, interests, and passions can change. If you're a maintainer but
+feel you must remove yourself from the list, inform other maintainers that you
+intend to step down, and if possible, help find someone to pick up your work.
+At the very least, ensure your work can be continued where you left off.
+
+After you've informed other maintainers, create a pull request to remove
+yourself from the MAINTAINERS file.
+"""
+
+    [Rules.inactive-maintainers]
+
+        title = "Removal of inactive maintainers"
+
+        text = """
+Similar to the procedure for adding new maintainers, existing maintainers can
+be removed from the list if they do not show significant activity on the
+project. Periodically, the maintainers review the list of maintainers and their
+activity over the last three months.
+
+If a maintainer has shown insufficient activity over this period, a neutral
+person will contact the maintainer to ask if they want to continue being
+a maintainer. If the maintainer decides to step down as a maintainer, they
+open a pull request to be removed from the MAINTAINERS file.
+
+If the maintainer wants to remain a maintainer, but is unable to perform the
+required duties they can be removed with a vote by the BDFL and at least 66% of
+the current maintainers. The BDFL's vote is mandatory. An e-mail is sent to the
+mailing list, inviting maintainers of the project to vote. The voting period is
+five business days. Issues related to a maintainer's performance should be
+discussed with them among the other maintainers so that they are not surprised
+by a pull request removing them.
+"""
+
+    [Rules.bdfl]
+
+        title = "The Benevolent dictator for life (BDFL)"
+
+        text = """
+Containerd follows the timeless, highly efficient and totally unfair system
+known as [Benevolent dictator for
+life](https://en.wikipedia.org/wiki/Benevolent_Dictator_for_Life), with yours
+truly, Solomon Hykes, in the role of BDFL. This means that all decisions are
+made, by default, by Solomon. Since making every decision himself would be
+highly un-scalable, in practice decisions are spread across multiple
+maintainers.
+
+Ideally, the BDFL role is like the Queen of England: awesome crown, but not an
+actual operational role day-to-day. The real job of a BDFL is to NEVER GO AWAY.
+Every other rule can change, perhaps drastically so, but the BDFL will always be
+there, preserving the philosophy and principles of the project, and keeping
+ultimate authority over its fate. This gives us great flexibility in
+experimenting with various governance models, knowing that we can always press
+the "reset" button without fear of fragmentation or deadlock. See the US
+congress for a counter-example.
+
+BDFL daily routine:
+
+* Is the project governance stuck in a deadlock or irreversibly fragmented?
+    * If yes: refactor the project governance
+* Are there issues or conflicts escalated by maintainers?
+    * If yes: resolve them
+* Go back to polishing that crown.
+"""
+
+    [Rules.decisions]
+
+        title = "How are decisions made?"
+
+        text = """
+Short answer: EVERYTHING IS A PULL REQUEST.
+
+Containerd is an open-source project with an open design philosophy. This means
+that the repository is the source of truth for EVERY aspect of the project,
+including its philosophy, design, road map, and APIs. *If it's part of the
+project, it's in the repo. If it's in the repo, it's part of the project.*
+
+As a result, all decisions can be expressed as changes to the repository. An
+implementation change is a change to the source code. An API change is a change
+to the API specification. A philosophy change is a change to the philosophy
+manifesto, and so on.
+
+All decisions affecting containerd, big and small, follow the same 3 steps:
+
+* Step 1: Open a pull request. Anyone can do this.
+
+* Step 2: Discuss the pull request. Anyone can do this.
+
+* Step 3: Merge or refuse the pull request. Who does this depends on the nature
+of the pull request and which areas of the project it affects.
+"""
+
+    [Rules.DCO]
+
+    title = "Helping contributors with the DCO"
+
+    text = """
+The [DCO or `Sign your work`](
+https://github.com/docker/containerd/blob/master/CONTRIBUTING.md#sign-your-work)
+requirement is not intended as a roadblock or speed bump.
+
+Some containerd contributors are not as familiar with `git`, or have used a web
+based editor, and thus asking them to `git commit --amend -s` is not the best
+way forward.
+
+In this case, maintainers can update the commits based on clause (c) of the DCO.
+The most trivial way for a contributor to allow the maintainer to do this, is to
+add a DCO signature in a pull requests's comment, or a maintainer can simply
+note that the change is sufficiently trivial that it does not substantially
+change the existing contribution - i.e., a spelling change.
+
+When you add someone's DCO, please also add your own to keep a log.
+"""
+
+    [Rules."no direct push"]
+
+    title = "I'm a maintainer. Should I make pull requests too?"
+
+    text = """
+Yes. Nobody should ever push to master directly. All changes should be
+made through a pull request.
+"""
+
+    [Rules.meta]
+
+    title = "How is this process changed?"
+
+    text = "Just like everything else: by making a pull request :)"
+
+# Current project roles
+[Roles]
+
+    [Roles.bdfl]
+
+    person = "shykes"
+
+    [Roles."Chief Architect"]
+
+    person = "crosbymichael"
+
+    text = """
+The chief architect is responsible for the overall integrity of the technical
+architecture across all subsystems, and the consistency of APIs and UI.
+
+Changes to UI, public APIs and overall architecture must be approved by the
+chief architect.
+"""
+
+    [Roles."Chief Maintainer"]
+
+    person = "crosbymichael"
+
+    text = """
+The chief maintainer is responsible for all aspects of quality for the project
+including code reviews, usability, stability, security, performance, etc.  The
+most important function of the chief maintainer is to lead by example. On the
+first day of a new maintainer, the best advice should be "follow the C.M.'s
+example and you'll be fine".
+"""
+
+# Current project organization
+[Org]
+
+	[Org.Maintainers]
+	people = [
+		"crosbymichael",
+		"dqminh",
+		"estesp",
+		"hqhq",
+		"jhowardmsft",
+		"mlaventure",
+		"stevooe",
+	]
+
+[People]
+
+    [People.crosbymichael]
+        Name = "Michael Crosby"
+        Email = "crosbymichael@gmail.com"
+        GitHub = "crosbymichael"
+
+    [People.dqminh]
+        Name = "Daniel, Dao Quang Minh"
+        Email = "dqminh89@gmail.com"
+        GitHub = "dqminh"
+
+    [People.estesp]
+        Name = "Phil Estes"
+        Email = "estesp@linux.vnet.ibm.com"
+        GitHub = "estesp"
+
+    [People.hqhq]
+        Name = "Qiang Huang"
+        Email = "h.huangqiang@huawei.com"
+        GitHub = "hqhq"
+
+    [People.jhowardmsft]
+        Name = "John Howard"
+        Email = "jhoward@microsoft.com"
+        GitHub = "jhowardmsft"
+
+    [People.mlaventure]
+        Name = "Kenfe-Mickaël Laventure"
+        Email = "mickael.laventure@docker.com"
+        GitHub = "mlaventure"
+
+    [People.stevvooe]
+        Name = "Stephen Day"
+        Email = "stephen.day@docker.com"
+        GitHub = "stevvooe"

README.md

@@ -1,6 +1,6 @@
 # containerd
 
-containerd is an industry-standard container runtime with an emphasis on simplicity, robustness and portability. It is a available as a daemon for Linux and Windows,  which can manage the complete container lifecycle of its host system: image transfer and storage, container execution and supervision, low-level storage and network attachments, etc..
+containerd is an industry-standard container runtime with an emphasis on simplicity, robustness and portability. It is available as a daemon for Linux and Windows, which can manage the complete container lifecycle of its host system: image transfer and storage, container execution and supervision, low-level storage and network attachments, etc..
 
 Containerd is designed to be embedded into a larger system, rather than being used directly by developers or end-users.
 
@@ -19,7 +19,7 @@ Containerd is designed to be embedded into a larger system, rather than being us
 Having a clearly defined scope of a project is important for ensuring consistency and focus.
 These following criteria will be used when reviewing pull requests, features, and changes for the project before being accepted.
 
-### Components 
+### Components
 
 Components should not have tight dependencies on each other so that they are unable to be used independently.
 The APIs for images and containers should be designed in a way that when used together the components have a natural flow but still be useful independently.
@@ -47,11 +47,11 @@ Additional implementations will not be accepted into the core repository and sho
 
 Containerd will be released with a 1.0 when feature complete and this version will be supported for 1 year with security and bug fixes applied and released.
 
-The upgrade path for containerd is that the 0.0.x patch relases are always backward compatible with its major and minor version.
+The upgrade path for containerd is that the 0.0.x patch releases are always backward compatible with its major and minor version.
 Minor (0.x.0) version will always be compatible with the previous minor release. i.e. 1.2.0 is backwards compatible with 1.1.0 and 1.1.0 is compatible with 1.0.0.
-There is no compatiability guarentes with upgrades from two minor relases.  i.e. 1.0.0 to 1.2.0.
+There is no compatibility guarantees with upgrades from two minor releases. i.e. 1.0.0 to 1.2.0.
 
-There are not backwards compatability guarentes with upgrades to major versions.  i.e 1.0.0 to 2.0.0.
+There are not backwards compatibility guarantees with upgrades to major versions. i.e 1.0.0 to 2.0.0.
 Each major version will be supported for 1 year with bug fixes and security patches.
 
 ### Scope
@@ -70,7 +70,7 @@ The table specifies whether or not the feature/component is in or out of scope.
 | logging | Persisting container logs | out | Logging can be build on top of containerd because the container’s STDIO will be provided to the clients and they can persist any way they see fit.,There is no io copying of container STDIO in containerd. |
 
 
-containerd is scoped to a single host and makes asumptions based on that fact.
+containerd is scoped to a single host and makes assumptions based on that fact.
 It can be used to builds things like a node agent that launches containers but does not have any concepts of a distributed system.
 
 Also things like service discovery are out of scope even though networking is in scope.
@@ -79,7 +79,7 @@ containerd should provide the primitives to create, add, remove, or manage netwo
 ### How is the scope changed?
 
 The scope of this project is a whitelist.
-If its not mentioned as being in scope, it is out of scope.  
+If it's not mentioned as being in scope, it is out of scope.  
 For the scope of this project to change it requires a 100% vote from all maintainers of the project.
 
 ## Copyright and license

ROADMAP.md

@@ -15,7 +15,7 @@ We would like to follow the roadmap and develop the components one by one to com
 
 **Status:** In Progress
 
-### GRPC API 
+### GRPC API
 
 **Documents:**
 
@@ -23,7 +23,7 @@ We are going from a top down design for filling out this missing pieces of conta
 
 ### Design
 
-**Documents:** 
+**Documents:**
 
 The high level design work is needed so that the architecture of containerd stays consistent throughout the development process.
 
@@ -46,7 +46,7 @@ This will also include moving the existing execution code support OCI's Runtime
 
 ### Runtime
 
-The runtime layer is responsible for the create of containers and the management and supervision of processes.
+The runtime layer is responsible for the creation of containers and their management, and supervision of the processes inside those containers.
 
 ### Storage
 
@@ -72,8 +72,11 @@ The networking component will allow the management of network namespaces and int
 
 ## Phase 4
 
-Phase 4 includes work on helping with the releases and packaging of containerd for various distros.
+Phase 4 involves graduating to version 1.0, and shifting the focus from features to maintenance. Graduating to 1.0 implies:
+
+- Completing all of the above phases.
+- Covering the functionalities required by a majority of container-centric platforms.
+- Offering feature parity, to the extent of technical possibilities, across Linux and Windows.
+- Demonstrating that containerd fulfills the requirements of at least one higher-level platforms through its complete integration as an upstream.
 
 **Status:** Not Started
-
-### Release Process & Tools