Repository: samza Updated Branches: refs/heads/master 8e61a4567 -> 603bd8eac
docs: update contact and contributor corner Also: - added a new page for 'Samza Enhancement Proposal' (SEP). - removed mailing-list.md and design-documents.md - updated the layout page Author: Peng Du <[email protected]> Reviewers: Jagadish<[email protected]> Closes #650 from pdu-mn1/docs-contact-contrib Project: http://git-wip-us.apache.org/repos/asf/samza/repo Commit: http://git-wip-us.apache.org/repos/asf/samza/commit/603bd8ea Tree: http://git-wip-us.apache.org/repos/asf/samza/tree/603bd8ea Diff: http://git-wip-us.apache.org/repos/asf/samza/diff/603bd8ea Branch: refs/heads/master Commit: 603bd8eac302046d9b876b716b2aea48b36df43c Parents: 8e61a45 Author: Peng Du <[email protected]> Authored: Tue Oct 2 23:06:27 2018 -0700 Committer: Jagadish <[email protected]> Committed: Tue Oct 2 23:06:27 2018 -0700 ---------------------------------------------------------------------- docs/_includes/footer.html | 4 +- docs/_includes/main-navigation.html | 2 +- docs/_layouts/default.html | 6 +- docs/_menu/index.html | 4 +- docs/community/contact-us.md | 77 +++++++++++++++++ docs/community/mailing-lists.md | 28 ------ docs/contribute/contributors-corner.md | 123 +++++++++++++-------------- docs/contribute/design-documents.md | 58 ------------- docs/contribute/enhancement-proposal.md | 96 +++++++++++++++++++++ 9 files changed, 240 insertions(+), 158 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/samza/blob/603bd8ea/docs/_includes/footer.html ---------------------------------------------------------------------- diff --git a/docs/_includes/footer.html b/docs/_includes/footer.html index 4ccf506..c0906ae 100644 --- a/docs/_includes/footer.html +++ b/docs/_includes/footer.html @@ -29,7 +29,7 @@ <div> <div class="footer__heading">Community</div> <div class="footer__items"> - <a class="footer__item" href="/community/mailing-lists.html">Contact Us</a> + <a class="footer__item" href="/community/contact-us.html">Contact Us</a> <a class="footer__item" href="/contribute/contributors-corner.html">Contributors' Corner</a> <a class="footer__item" href="/community/committers.html">PMC members and committers</a> <a class="footer__item" href="/powered-by/">Powered By</a> @@ -72,7 +72,7 @@ // do something with the status console.log(status); }); -</script> +</script> {% endif %} <!-- Google Analytics --> http://git-wip-us.apache.org/repos/asf/samza/blob/603bd8ea/docs/_includes/main-navigation.html ---------------------------------------------------------------------- diff --git a/docs/_includes/main-navigation.html b/docs/_includes/main-navigation.html index 626501e..827d18f 100644 --- a/docs/_includes/main-navigation.html +++ b/docs/_includes/main-navigation.html @@ -40,7 +40,7 @@ <i class="icon ion-md-arrow-dropdown"></i> </div> <div class="main-navigation__item-group-list"> - <a class="main-navigation__item" href="/community/mailing-lists.html">Contact Us</a> + <a class="main-navigation__item" href="/community/contact-us.html">Contact Us</a> <a class="main-navigation__item" href="/contribute/contributors-corner.html">Contributor's Corner</a> <a class="main-navigation__item" href="/community/committers.html">PMC Members and committers</a> <a class="main-navigation__item" href="/meetups/">Talks and Meetups</a> http://git-wip-us.apache.org/repos/asf/samza/blob/603bd8ea/docs/_layouts/default.html ---------------------------------------------------------------------- diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index bcc4a50..49f80a7 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -73,7 +73,7 @@ <div class="hero-blog-posts"> <h3>Latest from our blog</h3> <div class="blog-posts"> - + {% assign sortedBlogPost = site.blog | sort: 'date' | reverse %} {% assign maxCount = 3 %} {% assign latestCount = 1 %} @@ -94,7 +94,7 @@ <div class="blog-post__title">{{ post.title }}</div> <div class="blog-post__date">{{ post.date | date: "%B %-d, %Y" }}</div> </a> - + {% endfor %} </div> @@ -220,7 +220,7 @@ {% include footer.html %} <script type="text/javascript" src="/js/flickity.js"></script> - + </body> </html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/samza/blob/603bd8ea/docs/_menu/index.html ---------------------------------------------------------------------- diff --git a/docs/_menu/index.html b/docs/_menu/index.html index 038fd8b..ecf40d6 100644 --- a/docs/_menu/index.html +++ b/docs/_menu/index.html @@ -19,9 +19,11 @@ items: - menu_title: Community items: - menu_title: Contact Us - url: '/community/mailing-lists.html' + url: '/community/contact-us.html' - menu_title: Contributor's Corner url: '/contribute/contributors-corner.html' + - menu_title: Enhancement Proposal + url: '/contribute/enhancement-proposal.html' - menu_title: PMC members and committers url: '/community/committers.html' - menu_title: Talks and Meetups http://git-wip-us.apache.org/repos/asf/samza/blob/603bd8ea/docs/community/contact-us.md ---------------------------------------------------------------------- diff --git a/docs/community/contact-us.md b/docs/community/contact-us.md new file mode 100644 index 0000000..854e812 --- /dev/null +++ b/docs/community/contact-us.md @@ -0,0 +1,77 @@ +--- +layout: page +title: Contact Us +--- +<!-- + 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. +--> + +There are many ways to reach the Samza user and developer communities - use whichever one seems best! + +Please make sure you are subscribed to the mailing list you are posting to! If you are not subscribed to the mailing list, your message will be rejected. + +<table class="table table-condensed table-bordered table-striped"> + <thead> + <tr> + <th> How to contact us</th> + <th> When to use it </th> + </tr> + </thead> + <tbody> + <tr> + <td> <a href="https://lists.apache.org/[email protected]";>dev@</a> mailing list </td> + <td> General and Development discussions (<a href="mailto:[email protected]";>Subscribe</a>, <a href="mailto:[email protected]";>Unsubscribe</a>) </td> + </tr> + <tr> + <td> <a href="https://lists.apache.org/[email protected]";> commits@ </a> mailing list </td> + <td> Commits, bugs, pull requests, etc. (<a href="mailto:[email protected]";>Subscribe</a>, <a href="mailto:[email protected]";>Unsubscribe</a>) </td> + </tr> + <tr> + <td> <a href="https://issues.apache.org/jira/projects/SAMZA/issues/SAMZA-1371?filter=allopenissues";>JIRA</a> bug tracker </td> + <td> Report bugs / discover known issues </td> + </tr> + </tbody> +</table> + +If you would like to post to these mailing lists, please + +1. subscribe by sending an email using the **subscribe** links above; and +2. confirm the subscription by replying to the confirmation email; and +3. send your email to the mailing list. + +Please note that you wonât receive any responses to your email if you are not subscribed. + +### Having a Question? + +The Apache Samza community answers many user questions every day. You can search for answers and advices in the archives or reach out to the community for help and guidance. + +#### User Mailing List + +Many Samza users, contributors, and committers are subscribed to Samzaâs user mailing list. The user mailing list is a great place to get help. + +Some quick tips when using the mailing lists: + +* Prior to submitting questions, you can search the archive to find if the same questions have been asked before in [[email protected] mail archives](http://mail-archives.apache.org/mod_mbox/samza-dev/). +* For error logs or long code examples, please use [GitHub gist](https://gist.github.com/) and include only a few lines of the pertinent code / log within the email. +* No jobs, sales, or solicitation is permitted on the Apache Samza mailing lists. + +### Found a Bug? + +If you observe an unexpected behavior that might be caused by a bug, you can search for reported bugs or file a bug report in [Samzaâs JIRA](https://issues.apache.org/jira/projects/SAMZA/issues/SAMZA-1371?filter=allopenissues). More instructions are available in [contribors corner](/contribute/contributors-corner.html). + +If you are unsure whether the unexpected behavior was a bug or not, please post a question to the [user mailing list](mailto:[email protected]). + + http://git-wip-us.apache.org/repos/asf/samza/blob/603bd8ea/docs/community/mailing-lists.md ---------------------------------------------------------------------- diff --git a/docs/community/mailing-lists.md b/docs/community/mailing-lists.md deleted file mode 100644 index ebf041c..0000000 --- a/docs/community/mailing-lists.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -layout: page -title: Mailing Lists ---- -<!-- - 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. ---> - -We have a few mailing lists hosted by Apache: - -* **[email protected]** <small>([subscribe](mailto:[email protected]), [unsubscribe](mailto:[email protected]), [archive](http://mail-archives.apache.org/mod_mbox/samza-dev/))</small><br/> - A list for discussion on Samza development. Email here for help. - -* **[email protected]** <small>([subscribe](mailto:[email protected]), [unsubscribe](mailto:[email protected]), [archive](http://mail-archives.apache.org/mod_mbox/samza-commits/))</small><br/> - A list to track Samza commits. http://git-wip-us.apache.org/repos/asf/samza/blob/603bd8ea/docs/contribute/contributors-corner.md ---------------------------------------------------------------------- diff --git a/docs/contribute/contributors-corner.md b/docs/contribute/contributors-corner.md index 454ce59..c3ad9ce 100644 --- a/docs/contribute/contributors-corner.md +++ b/docs/contribute/contributors-corner.md @@ -21,17 +21,30 @@ title: Contributor's Corner - [Ask Questions](#ask-questions) - [File Bug Reports](#file-bug-reports) - [Find A Project to Work On](#find-a-project-to-work-on) +- [Contributing Documentation](#contributing-documentation) - [Contributing to Apache Samza](#contributing-to-apache-samza) -- [For Committers](#for-committers) - * [Prepare to merge a Pull Request (PR) by setting up the following:](#prepare-to-merge-a-pull-request--pr--by-setting-up-the-following-) - * [Merging a Pull Request](#merging-a-pull-request) - -Apache Samza is developed by an open and friendly community. Everybody is welcome to contribute and engage with the community. We are happy to accept contributions, be it trivial cleanups or bug-fixes or new features. There are many ways to engage with the community and contribute to Apache Samza, including filing bugs, asking questions and joining discussions in our mailing lists, contributing code or documentation, or testing. + * [Building and Testing](#building-and-testing) + * [Developing with an IDE](#developing-with-an-ide) +- [Pull Requests](#pull-requests) + +Apache Samza is developed by an open and friendly community. Everybody is welcome to contribute and engage with the community. There are many such opportunities: + +* ask or answer questions +* review proposed design ideas +* improve the documentation +* contribute bug reports +* write new sample applications +* add new or improve existing test cases +* add new libraries (new IO systems, etc) +* work on the core Samza stream processing framework +* review design proposals and documents ## Ask Questions -Apache Samza community is happy to answer any questions related to the project. We use our [mailing list](/community/mailing-lists.html) for all communications and discussions. You can also interact in StackOverflow under the tag - [#apache-samza](http://stackoverflow.com/questions/tagged/apache-samza) + +Apache Samza community is happy to answer any questions related to the project with any communication channels listed in [mailing list](/community/contact-us.html). ## File Bug Reports + Apache Samza uses [JIRA](https://issues.apache.org/jira/browse/SAMZA) to file bug reports. In order to file a bug report, please open Samza JIRA and include the following details: * A descriptive title @@ -39,78 +52,58 @@ Apache Samza uses [JIRA](https://issues.apache.org/jira/browse/SAMZA) to file bu * Version of Apache Samza in which this issue is seen - You can add the version(s) by updating "Affects Version/s" field in the JIRA * Environment details (such as OS, JDK version etc) whenever applicable -If you need someone to immediately take a look at your JIRA, please don't hesitate to send an email to the dev mailing list. +If you need someone to immediately take a look at your JIRA, please donât hesitate to send an email to the [dev mailing list](mailto:[email protected]). ## Find A Project to Work On -We tag bugs in [JIRA](https://issues.apache.org/jira/browse/SAMZA) with "[newbie](https://issues.apache.org/jira/issues/?jql=project%20%3D%20SAMZA%20AND%20labels%20%3D%20newbie%20AND%20status%20%3D%20Open)" label that are good for people getting started with the code base. When you feel confident, you can pick-up "[newbie++](https://issues.apache.org/jira/issues/?jql=project%20%3D%20SAMZA%20AND%20labels%20%3D%20%22newbie%2B%2B%22%20AND%20status%20%3D%20Open)" JIRAs. Picking up these JIRAs are the best way to familiarize yourself with the codebase. +We tag tickets in [JIRA](https://issues.apache.org/jira/browse/SAMZA) with â[newbie](https://issues.apache.org/jira/issues/?jql=project%20%3D%20SAMZA%20AND%20labels%20%3D%20newbie%20AND%20status%20%3D%20Open)â label that are good for people getting started with the code base. When you feel confident, you can pick-up â[newbie++](https://issues.apache.org/jira/issues/?jql=project%20%3D%20SAMZA%20AND%20labels%20%3D%20%22newbie%2B%2B%22%20AND%20status%20%3D%20Open)â JIRAs. Picking up these JIRAs are the best way to familiarize yourself with the codebase. -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: +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 documented in details in [samza enhancement proposal](/contribute/enhancement-proposal.html). +If you are unclear whether a change you are proposing requires a design document, ask us through our [mailing list](mailto:[email protected]). -1. Instigate a discussion on the [JIRA](https://issues.apache.org/jira/browse/SAMZA) -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 +## Contributing Documentation -*If you are unclear whether a change you are proposing requires a design document, feel free ask us through our mailing list!* +The Samza documentation is based on markdown files, which are built using Jekyll. To propose a change to documentation, edit their corresponding markdown source files in Samzaâs [docs/](https://github.com/apache/samza/tree/master/docs) directory. The [README.md](https://github.com/apache/samza/blob/master/docs/README.md) in the same directory shows how to build the documentation locally and test your changes. The process to propose a doc change is otherwise the same as the process for proposing code changes below. ## Contributing to Apache Samza -Samza's code is in an Apache Git repository located [here](https://git-wip-us.apache.org/repos/asf?p=samza.git;a=tree). +The official Samza codebase is hosted on the Apache Git repository located [here](https://github.com/apache/samza) and we use [Pull Requests](https://help.github.com/articles/about-pull-requests/) on [GitHub](https://github.com/apache/samza) for code reviews. If you are unfamiliar with this workflow, [Git Handbook](https://guides.github.com/introduction/git-handbook/) has many useful introductions and instructions. + +You should [fork](https://guides.github.com/activities/forking/) the [Samzaâs Github repository](https://github.com/apache/samza) to create your own repository. + +### Building and Testing -You can check out Samza's code by running: +We use [Gradle](https://gradle.org/) to build and test Samza. You do not need to install gradle, but you do need a Java SDK installed. You can develop on Linux and macOS. + +The entire set of unit tests can be run with this command at the root of the git repository. ``` -git clone http://git-wip-us.apache.org/repos/asf/samza.git +./gradlew test ``` -The Samza website is built by Jekyll from the markdown files found in the `docs` subdirectory. - -We use Pull Requests to review and discuss your contributions. In order to contribute code, please do the following: - -* If you are working on a big new feature, follow the steps outlined above regarding [design documents](/contribute/design-documents.html) page -* If there is no JIRA for your work, please open a [JIRA](https://issues.apache.org/jira/browse/SAMZA) before creating a Pull Request. If it is a trivial fix (such as typo, doc fix etc), you may skip the JIRA creation. -* Creating Pull Request - 1. Fork the Github repository at [http://github.com/apache/samza](http://github.com/apache/samza) if you haven't already - 2. Create a new branch in your repository and push your changes to that branch - * Make sure you have observed the recommendations in the [coding guide](/contribute/coding-guide.html) and [testing](/contribute/tests.html) - 3. [Open a Pull Request](https://help.github.com/articles/about-pull-requests/) against the "master" branch of apache/samza - * Make sure that the Pull Request title is of the format "SAMZA-<JiraNumber> : <JiraTitle>" - * Make sure that your patch cleanly applies against the master branch. If not, rebase before creating the Pull Request - 4. Change the status of the JIRA to "Patch Available" so that it notifies the committers of the patch being available -* Nag us if we don't follow up on your JIRA in a timely fashion. -* If your Pull Request is approved, it will automatically be closed, with any associated JIRA when a committer merges your changes. -* If your Pull Request is not approved and requires changes based on reviews, please make changes to your patch. - * While making the changes, kindly update the JIRA status from "Patch Available" to "In Progress". - * Make sure that you have rebased your branch to latest in the master branch before updating the Pull Request. This will help avoid conflicts during the merge. We cannot commit patches that have merge conflicts! -* If your Pull Request is rejected for whatever reason, please close it promptly because committers cannot close your Pull Requests! - -## For Committers - -If you are a committer you need to use https instead of http to check in, otherwise you will get an error regarding an inability to acquire a lock. Note that older versions of git may also give this error even when the repo was cloned with https; if you experience this try a newer version of git. - -### Prepare to merge a Pull Request (PR) by setting up the following: - -1. Setup JIRA on your host - * Install Jira packages - ```sudo pip install jira``` - * Set the `JIRA_USERNAME` and `JIRA_PASSWORD` environment variables with the appropriate credentials for interacting with Jira. This is required to correctly close the JIRA associated with the PR -2. Setup aliases for the remote repositories:â(Samza Github repo and Apache Samza Repo) - * Add ASF git repo for committing the PR - ```git remote add samza-apache https://git-wip-us.apache.org/repos/asf/samza.git``` - * Add Github repo for fetching the patch from the PR - ```git remote add samza-github https://github.com/apache/samza.git``` -3. Set up API tokens for Git - * Create an OAuth key for making requests to the GitHub API. If this is not defined, then requests will be unauthenticated and you can't access the API. An OAuth key for the API can be created at [https://github.com/settings/tokens](https://github.com/settings/tokens) - * Set the created OAuth key as `GITHUB_OAUTH_KEY` environment variable. - -### Merging a Pull Request - -* Committers can use the `bin/merge-pull-request.py` script to merge an approved PR. The script is interactive and will walk you through the steps for merging the patch, closing the PR and the associated JIRA. +### Developing with an IDE + +Generate an IDEA project .ipr file with: + ``` -cd samza -./bin/merge-pull-request.py +./gradlew idea ``` -* Whenever possible, make sure that the commit title includes the JIRA number and title. -* Merging changes that don't cleanly apply on the master should be avoided. -* For committers wishing to update the webpage, please see `docs/README.md` for instructions. + +## Pull Requests + +If there is no [JIRA](https://issues.apache.org/jira/browse/SAMZA) ticket for your work, please open one before creating a Pull Request. If it is a trivial fix (such as a typo, doc fix etc), you may skip ticket creation. Hereâs the development workflow: + +* Create a new branch in your repository and push your changes to that branch + * Make sure you have observed the recommendations in the [coding guide](/contribute/coding-guide.html) and [testing](/contribute/tests.html) +* [Open a Pull Request](https://help.github.com/articles/about-pull-requests/) against the âmasterâ branch of apache/samza + * Make sure that the Pull Request title is of the format "SAMZA-<JiraNumber> : <JiraTitle>" + * Make sure that your patch cleanly applies against the master branch. If not, rebase before creating the Pull Request + * Optional: add a reviewer by @ the username +* [Ping us](mailto:[email protected]) if we donât follow up on your JIRA in a timely fashion. +* If your Pull Request is approved, it will automatically be closed, along with any associated JIRA ticket when a committer merges your changes. +* If your Pull Request is not approved and requires changes based on reviews, please make changes and update the Pull Request. + * Fixes can simply be pushed to the same branch from which you opened your pull request. + * Please address feedback via additional commits instead of amending existing commits. This makes it easier for the reviewers to know what has changed since the last review. + * Jenkins will automatically re-test when new commits are pushed. + * Despite our efforts, Samza may have flaky tests at any given point, if the failure is unrelated to your pull request and you have been able to run the tests locally successfully, please mention it in the pull request. +* If your Pull Request is rejected or discarded for whatever reason, please close it promptly because committers cannot close your Pull Requests since committers cannot close them. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/samza/blob/603bd8ea/docs/contribute/design-documents.md ---------------------------------------------------------------------- diff --git a/docs/contribute/design-documents.md b/docs/contribute/design-documents.md deleted file mode 100644 index 5729aa8..0000000 --- a/docs/contribute/design-documents.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -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/samza/blob/603bd8ea/docs/contribute/enhancement-proposal.md ---------------------------------------------------------------------- diff --git a/docs/contribute/enhancement-proposal.md b/docs/contribute/enhancement-proposal.md new file mode 100644 index 0000000..d2cc23f --- /dev/null +++ b/docs/contribute/enhancement-proposal.md @@ -0,0 +1,96 @@ +--- +layout: page +title: Samza Enhancement Proposal +--- +<!-- + 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 is a SEP needed](#when-is-a-sep-needed) +- [What is the SEP Process](#what-is-the-sep-process) +- [What should be included in SEP](#what-should-be-included-in-sep) +- [What are the criteria to accept or reject a SEP](#what-are-the-criteria-to-accept-or-reject-a-sep) + +*Samza Enhancement Proposal* (SEP) is the official process for proposing major changes to Apache Samza. All technical decisions in Samza have pros and cons - Having a SEP helps us capture the thought process that lead to a decision. + +We want to make Samza a core architectural component for users. Samza also supports a large number of integrations with other tools, systems, and clients. Keeping these kinds of usages healthy requires a high level of compatibility across releases. As a result each new major feature or public API has to be done in a way that we can stick with it going forward. + +Note that this process isn't meant to discourage incompatible changes. Rather it is intended to avoid accidentally introducing half thought-out interfaces and protocols that cause needless heartburn when changed. + +## When is a SEP needed + +Any major **functional** change to Samza's core functionality, that is changes to the behavior of the classes in samza-core package requires a SEP. + +Any of the following should be considered a major change: + +* major new feature, subsystem, or piece of functionality +* change that impacts the public interfaces of the project + +The following are treated as public interfaces: + +* Classes in the public package - samza-api +* Configurations in Samza +* Metrics reported by Samza +* Command line tools and their arguments + +## What is the SEP Process + +1. Create a page which is a child of [this one](https://cwiki.apache.org/confluence/display/SAMZA/Samza+Enhancement+Proposal). Take the next available SEP number and give your proposal a descriptive heading. e.g. "SEP 73: Samza Standalone with ZK Coordination". If you don't have the necessary permissions for creating a new page, please ask on the [dev mailing list](mailto:[email protected]). +2. Fill in the sections as described in [What should be included in SEP](#what-should-be-included-in-sep). +3. Start a [DISCUSS] thread on the Apache mailing list. Please ensure that the subject of the thread is of the format [DISCUSS] SEP-{your SEP number} {your SEP heading}. The discussion should happen on the mailing list and **NOT** on the wiki since the wiki comment system doesn't work well for larger discussions. In the process of the discussion you may update the proposal. You should let people know the changes you are making. +4. Once the proposal is finalized call a [VOTE] to have the proposal adopted. These proposals are more serious than code changes and more serious even than release votes. The criterion for acceptance is lazy majority. +5. Please update the SEP wiki page to reflect the current stage of the SEP after a vote. This acts as the permanent record indicating the result of the SEP (e.g., Accepted or Rejected). Also report the result of the SEP vote to the voting thread on the mailing list so the conclusion is clear. + +## What should be included in SEP + +A typical SEP should include the following sections: + +* **Problem**: Describe the problem to be solved +* **Motivation**: Why the problem should be solved +* **Proposed Changes**: Describe the changes you want to do. This may be fairly extensive and have large subsections of its own. Or it may be a few sentences, depending on the scope of the change. +* **New or changed public interfaces, if any**: Impact to any of the "compatibility commitments" described above. We want to call these out in particular, so everyone thinks about them. +* **Implementation / Test Plan (if applicable)**: Some large projects may consist of multiple sub-projects and requires more planning for implementation and testing. It may be prudent to call them out in the proposal. +* **Migration Plan and Compatibility**: If this feature requires additional support for a no-downtime upgrade describe how that will work. If a no-downtime upgrade for users cannot be support, describe the migration plan for the users. +* **Rejected Alternatives**: What are the other alternatives you considered and why are they worse? The goal of this section is to help people understand why this is the best solution now, and also to prevent churn in the future when old alternatives are reconsidered. + +## What are the criteria to accept or reject a SEP + +We will be following the [Apache voting guideline](https://www.apache.org/foundation/voting.html) to drive our decisions regarding an SEP. Decisions will be made on the [VOTE] mailing thread for a particular SEP. All community members are encouraged to participate by replying to the VOTE mailing thread. The votes can have the following meaning: + +<table class="table table-condensed table-bordered table-striped"> + <thead> + <tr> + <th align="center">Vote</th> + <th align="center">Meaning</th> + </tr> + </thead> + <tbody> + <tr> + <td align="center">+1</td> + <td>'Yes,' 'Agree,' or 'the action should be performed.'</td> + </tr> + <tr> + <td align="center">0</td> + <td>Neutral about the proposed action (or mildly negative but not enough so to want to block it.</td> + </tr> + <tr> + <td align="center">-1</td> + <td>This is a negative vote. On issues where consensus is required, this vote counts as a **veto**. All vetoes must contain an explanation of why the veto is appropriate. Vetoes with no explanation are void. It may also be appropriate for a -1 vote to include an alternative course of action. </td> + </tr> + </tbody> +</table> + +The criteria for acceptance of a SEP is [lazy majority](https://cwiki.apache.org/confluence/display/KAFKA/Bylaws#Bylaws-Approvals).
