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 <[email protected]> Authored: Thu Sep 11 12:21:57 2014 -0700 Committer: Chris Riccomini <[email protected]> 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).
