Repository: samza Updated Branches: refs/heads/master e6956a37b -> 36bcbacc2
SAMZA-1030; Add documentation for change in the contribution process I re-organized some of the website files and created a "Contributor's Corner" that collates all info related to new contributors and committers Also, updated the merge script with constants to match from the website documentation. Author: Navina Ramesh <nram...@linkedin.com> Reviewers: Jagadish <jagad...@apache.org> Closes #16 from navina/adding-docs Project: http://git-wip-us.apache.org/repos/asf/samza/repo Commit: http://git-wip-us.apache.org/repos/asf/samza/commit/36bcbacc Tree: http://git-wip-us.apache.org/repos/asf/samza/tree/36bcbacc Diff: http://git-wip-us.apache.org/repos/asf/samza/diff/36bcbacc Branch: refs/heads/master Commit: 36bcbacc27faf07621fad44e8edea58eafb94fae Parents: e6956a3 Author: Navina Ramesh <nram...@linkedin.com> Authored: Thu Sep 29 18:09:04 2016 -0700 Committer: vjagadish1989 <jvenk...@linkedin.com> Committed: Thu Sep 29 18:09:04 2016 -0700 ---------------------------------------------------------------------- bin/merge-pull-request.py | 4 +- docs/_layouts/default.html | 4 +- docs/contribute/code.md | 6 +- docs/contribute/coding-guide.md | 7 ++ docs/contribute/contributors-corner.md | 116 ++++++++++++++++++++++++++++ docs/contribute/projects.md | 34 -------- docs/contribute/rules.md | 40 ---------- 7 files changed, 128 insertions(+), 83 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/samza/blob/36bcbacc/bin/merge-pull-request.py ---------------------------------------------------------------------- diff --git a/bin/merge-pull-request.py b/bin/merge-pull-request.py index 46c67e4..5f1dae7 100755 --- a/bin/merge-pull-request.py +++ b/bin/merge-pull-request.py @@ -51,9 +51,9 @@ PROJECT_NAME = "samza" CAPITALIZED_PROJECT_NAME = "samza".upper() # Remote name which points to the GitHub site -PR_REMOTE_NAME = os.environ.get("PR_REMOTE_NAME", "apache-github") +PR_REMOTE_NAME = os.environ.get("PR_REMOTE_NAME", "samza-github") # Remote name which points to Apache git -PUSH_REMOTE_NAME = os.environ.get("PUSH_REMOTE_NAME", "apache") +PUSH_REMOTE_NAME = os.environ.get("PUSH_REMOTE_NAME", "samza-apache") # ASF JIRA username JIRA_USERNAME = os.environ.get("JIRA_USERNAME", "") # ASF JIRA password http://git-wip-us.apache.org/repos/asf/samza/blob/36bcbacc/docs/_layouts/default.html ---------------------------------------------------------------------- diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index d20e603..60e56b5 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -92,12 +92,10 @@ <h1><i class="fa fa-code"></i> Contribute</h1> <ul> - <li><a href="/contribute/rules.html">Rules</a></li> + <li><a href="/contribute/contributors-corner.html">Contributor's Corner</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/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="/contribute/tests.html">Tests</a></li> </ul> http://git-wip-us.apache.org/repos/asf/samza/blob/36bcbacc/docs/contribute/code.md ---------------------------------------------------------------------- diff --git a/docs/contribute/code.md b/docs/contribute/code.md index be85c8d..2ebe354 100644 --- a/docs/contribute/code.md +++ b/docs/contribute/code.md @@ -27,8 +27,6 @@ You can check out Samza's code by running: git clone http://git-wip-us.apache.org/repos/asf/samza.git ``` -Please see the [Rules](rules.html) page for information on how to contribute. +Official releases can be downloaded from [here](/startup/download) -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. - -The Samza website is built by Jekyll from the markdown files found in the docs subdirectory. For committers wishing to update the webpage, please see `docs/README.md` for instructions. +Please see [Contributor's Corner'](rules.html) for information on how to contribute. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/samza/blob/36bcbacc/docs/contribute/coding-guide.md ---------------------------------------------------------------------- diff --git a/docs/contribute/coding-guide.md b/docs/contribute/coding-guide.md index 659834f..260c488 100644 --- a/docs/contribute/coding-guide.md +++ b/docs/contribute/coding-guide.md @@ -22,6 +22,13 @@ title: Coding Guide <!-- TODO link to hudson when we have an apache hudson boxes. --> These guidelines are meant to encourage consistency and best practices amongst people working on the Samza code base. They should be observed unless there is a compelling reason to ignore them. +In general, patches should include: + +* Code change +* Unit tests +* Javadocs +* Metrics +* Logging ### Basic Stuff http://git-wip-us.apache.org/repos/asf/samza/blob/36bcbacc/docs/contribute/contributors-corner.md ---------------------------------------------------------------------- diff --git a/docs/contribute/contributors-corner.md b/docs/contribute/contributors-corner.md new file mode 100644 index 0000000..0e1cc0f --- /dev/null +++ b/docs/contribute/contributors-corner.md @@ -0,0 +1,116 @@ +--- +layout: page +title: Contributor's Corner +--- +<!-- + 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. +--> +- [Ask Questions](#ask-questions) +- [File Bug Reports](#file-bug-reports) +- [Find A Project to Work On](#find-a-project-to-work-on) +- [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-fix 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. + +## 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) + +## 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 +* Description of the issue you are facing +* 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. + +## 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. + +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 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 + +*If you are unclear whether a change you are proposing requires a design document, feel free ask us through our mailing list!* + +## 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). + +You can check out Samza's code by running: + +``` +git clone http://git-wip-us.apache.org/repos/asf/samza.git +``` + +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. +``` +cd samza +./bin/merge-pull-request.py +``` +* 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. http://git-wip-us.apache.org/repos/asf/samza/blob/36bcbacc/docs/contribute/projects.md ---------------------------------------------------------------------- diff --git a/docs/contribute/projects.md b/docs/contribute/projects.md deleted file mode 100644 index ff01797..0000000 --- a/docs/contribute/projects.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -layout: page -title: Projects ---- -<!-- - 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. ---> - -### Newbies - -We tag bugs in [JIRA](https://issues.apache.org/jira/browse/SAMZA) with "newbie" that are good for people getting started with the code base. You can find the list [here](https://issues.apache.org/jira/issues/?jql=project%20%3D%20SAMZA%20AND%20labels%20%3D%20newbie%20AND%20status%20%3D%20Open). - -### Larger Chunks of Work - -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 [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/samza/blob/36bcbacc/docs/contribute/rules.md ---------------------------------------------------------------------- diff --git a/docs/contribute/rules.md b/docs/contribute/rules.md deleted file mode 100644 index 419eedd..0000000 --- a/docs/contribute/rules.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -layout: page -title: Rules ---- -<!-- - 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. --> - -We are always very happy to have code contributions whether for trivial cleanups or big new features. In general, patches should include: - -* Code change -* Unit tests -* Javadocs -* Metrics -* Logging - -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 [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. -* Open a [Review Board](https://reviews.apache.org/groups/samza/) ticket with your patch attached. -* Post a link to the RB code review on the JIRA ticket. -* Nag us if we don't follow up on your JIRA in a timely fashion.
