You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@samza.apache.org by cr...@apache.org on 2014/09/11 21:22:04 UTC
git commit: update SEPs section on page to use design docs on JIRAs
instead
Repository: incubator-samza
Updated Branches:
refs/heads/master f5778447e -> 38f421f00
update SEPs section on page to use design docs on JIRAs instead
Project: http://git-wip-us.apache.org/repos/asf/incubator-samza/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-samza/commit/38f421f0
Tree: http://git-wip-us.apache.org/repos/asf/incubator-samza/tree/38f421f0
Diff: http://git-wip-us.apache.org/repos/asf/incubator-samza/diff/38f421f0
Branch: refs/heads/master
Commit: 38f421f003826b919a845e75381891773d044fa5
Parents: f577844
Author: Chris Riccomini <cr...@criccomi-mn.linkedin.biz>
Authored: Thu Sep 11 12:21:57 2014 -0700
Committer: Chris Riccomini <cr...@criccomi-mn.linkedin.biz>
Committed: Thu Sep 11 12:21:57 2014 -0700
----------------------------------------------------------------------
docs/_layouts/default.html | 2 +-
docs/contribute/design-documents.md | 58 ++++++++++++++++++++++++++++++++
docs/contribute/projects.md | 4 +--
docs/contribute/rules.md | 2 +-
docs/contribute/seps.md | 43 -----------------------
5 files changed, 62 insertions(+), 47 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/38f421f0/docs/_layouts/default.html
----------------------------------------------------------------------
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
index bb21385..870ac99 100644
--- a/docs/_layouts/default.html
+++ b/docs/_layouts/default.html
@@ -88,7 +88,7 @@
<li><a href="/contribute/rules.html">Rules</a></li>
<li><a href="/contribute/coding-guide.html">Coding Guide</a></li>
<li><a href="/contribute/projects.html">Projects</a></li>
- <li><a href="/contribute/seps.html">SEPs</a></li>
+ <li><a href="/contribute/design-documents.html">Design Documents</a></li>
<li><a href="/contribute/code.html">Code</a></li>
<li><a href="https://reviews.apache.org/groups/samza">Review Board</a></li>
<li><a href="https://builds.apache.org/">Unit Tests</a></li>
http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/38f421f0/docs/contribute/design-documents.md
----------------------------------------------------------------------
diff --git a/docs/contribute/design-documents.md b/docs/contribute/design-documents.md
new file mode 100644
index 0000000..5729aa8
--- /dev/null
+++ b/docs/contribute/design-documents.md
@@ -0,0 +1,58 @@
+---
+layout: page
+title: Design Documents
+---
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+When making larger changes to Samza, or working on a [project](/contribute/projects.html), please write a design document. All of Samza's existing design documents can be found [here](https://issues.apache.org/jira/issues/?jql=project%20%3D%20SAMZA%20AND%20labels%20%3D%20design%20ORDER%20BY%20priority%20DESC).
+
+### Why Write a Design Document?
+
+The goal of the design document is to:
+
+1. Define the problem you're trying to solve.
+2. Propose a solution, and explore alternatives.
+3. Instigate discussion on the issue.
+4. Arrive at a final conclusion on design.
+5. Archive design documents for future use.
+
+It may be necessary to iterate on the design document several times before a final conclusion is reached.
+
+### How to Write a Design Document
+
+Design documents should be attached to the [JIRA](https://issues.apache.org/jira/browse/SAMZA) for the feature that the design is for. The [JIRA](https://issues.apache.org/jira/browse/SAMZA) should be labeled with the "design" label.
+
+There is no single format for a design document, but it's common to include:
+
+1. Introduction
+2. Definition of problem
+3. Possible solutions
+4. Opinion on best solution
+5. Details on how the solution should be implemented.
+
+An example of a design document can be seen on [SAMZA-402](https://issues.apache.org/jira/browse/SAMZA-402), which contains several versions of both the raw [Markdown](http://daringfireball.net/projects/markdown/syntax) file and the PDF for the design document.
+
+### Tools
+
+Some useful tools for writing design documents are:
+
+* [Markdown](http://daringfireball.net/projects/markdown/syntax): A syntax for writing well-formatted text-based documents.
+* [asciiflow.com](http://asciiflow.com): A webpage to draw flow charts using ASCII. This is useful for design docs written in text formats such as markdown.
+* [Markdown Reader](https://chrome.google.com/webstore/detail/markdown-reader/gpoigdifkoadgajcincpilkjmejcaanc): A Chrome extension that lets you view markdown (.md) files in Chrome. Once viewed in Chrome, the markdown file can be printed on a Mac simply by printing the page, and selecting "Save as PDF" as the printer.
+* [TLA/TLA+](http://research.microsoft.com/en-us/um/people/lamport/tla/tla.html): A formal specification language for writing high-level specifications of concurrent and distributed systems.
+* [Pandoc](http://johnmacfarlane.net/pandoc/): A tool for converting various text formats into one another. Pandoc supports converting [Markdown](http://daringfireball.net/projects/markdown/syntax) to PDF, among others.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/38f421f0/docs/contribute/projects.md
----------------------------------------------------------------------
diff --git a/docs/contribute/projects.md b/docs/contribute/projects.md
index 2a0c72c..ff01797 100644
--- a/docs/contribute/projects.md
+++ b/docs/contribute/projects.md
@@ -28,7 +28,7 @@ We tag bugs in [JIRA](https://issues.apache.org/jira/browse/SAMZA) with "newbie"
More meaty projects are [here](https://issues.apache.org/jira/issues/?jql=project%20%3D%20SAMZA%20AND%20labels%20%3D%20project%20AND%20status%20%3D%20Open). The process for working on a large project is:
1. Instigate discussion on the [JIRA](https://issues.apache.org/jira/browse/SAMZA).
-2. Write a [SEP](seps.html) (Samza Enhancement Proposal).
-3. Request feedback for the [SEP](seps.html) on the Jira and the samza-dev mailing list.
+2. Write a [design document](design-documents.html).
+3. Request feedback for the [design document](design-documents.html) on the Jira and the samza-dev mailing list.
4. Come to an agreement on design.
5. Implement design.
http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/38f421f0/docs/contribute/rules.md
----------------------------------------------------------------------
diff --git a/docs/contribute/rules.md b/docs/contribute/rules.md
index d7abbab..419eedd 100644
--- a/docs/contribute/rules.md
+++ b/docs/contribute/rules.md
@@ -31,7 +31,7 @@ We are always very happy to have code contributions whether for trivial cleanups
To submit a patch for inclusion please do the following:
-* If you are working on a big new feature ([project](projects.html)), follow the steps outlined on the [SEPs](/contribute/seps.html) page.
+* If you are working on a big new feature ([project](projects.html)), follow the steps outlined on the [design documents](/contribute/design-documents.html) page.
* Create a patch that applies cleanly against trunk.
* Make sure you have observed the recommendations in the style guide.
* Open a [JIRA](https://issues.apache.org/jira/browse/SAMZA) ticket describing the patch and attach your patch to the JIRA.
http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/38f421f0/docs/contribute/seps.md
----------------------------------------------------------------------
diff --git a/docs/contribute/seps.md b/docs/contribute/seps.md
deleted file mode 100644
index dc84ccb..0000000
--- a/docs/contribute/seps.md
+++ /dev/null
@@ -1,43 +0,0 @@
----
-layout: page
-title: Samza Enhancement Proposals
----
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
-<!-- TODO link to jira when we have an apache jira. -->
-
-When making larger changes to Samza, or working on a [project](/contribute/projects.html), please write a Samza Enhancement Proposal (SEP) on the Samza wiki. The goal of the SEP is to:
-
-1. Define the problem you're trying to solve
-2. Propose a solution, and explore alternatives.
-3. Instigate discussion on the issue.
-4. Archive design documents for future use.
-
-### How to Write a SEP
-
-SEPs are stored on the Samza wiki. To write a SEP, create a new sub page on the wiki with a title formatted as SEP-# (e.g. SEP-24).
-
-There is no set single format for a SEP, but it's common to include:
-
-1. Table of Contents
-2. Introduction
-3. Definition of problem
-4. Possible solutions
-5. Opinion on best solution
-6. Proposed metrics to add.
-7. A link to the [JIRA](https://issues.apache.org/jira/browse/SAMZA).