Fix hyphens in url for committer instructions
[samza.git] / docs / contribute / contributors-corner.md
1 ---
2 layout: page
3 title: Contributor's Corner
4 ---
5 <!--
6    Licensed to the Apache Software Foundation (ASF) under one or more
7    contributor license agreements.  See the NOTICE file distributed with
8    this work for additional information regarding copyright ownership.
9    The ASF licenses this file to You under the Apache License, Version 2.0
10    (the "License"); you may not use this file except in compliance with
11    the License.  You may obtain a copy of the License at
12
13        http://www.apache.org/licenses/LICENSE-2.0
14
15    Unless required by applicable law or agreed to in writing, software
16    distributed under the License is distributed on an "AS IS" BASIS,
17    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18    See the License for the specific language governing permissions and
19    limitations under the License.
20 -->
21 - [Ask Questions](#ask-questions)
22 - [File Bug Reports](#file-bug-reports)
23 - [Find A Project to Work On](#find-a-project-to-work-on)
24 - [Contributing to Apache Samza](#contributing-to-apache-samza)
25 - [For Committers](#for-committers)
26   * [Prepare to merge a Pull Request (PR) by setting up the following:](#prepare-to-merge-a-pull-request--pr--by-setting-up-the-following-)
27   * [Merging a Pull Request](#merging-a-pull-request)
28
29 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.
30
31 ## Ask Questions
32 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)
33
34 ## File Bug Reports
35 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:
36
37 * A descriptive title
38 * Description of the issue you are facing
39 * 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
40 * Environment details (such as OS, JDK version etc) whenever applicable
41  
42 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.
43
44 ## Find A Project to Work On
45
46 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. 
47
48 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:
49
50 1. Instigate a discussion on the [JIRA](https://issues.apache.org/jira/browse/SAMZA)
51 2. Write a [design document](design-documents.html)
52 3. Request feedback for the [design document](design-documents.html) on the Jira and the samza-dev mailing list
53 4. Come to an agreement on design
54 5. Implement design
55
56 *If you are unclear whether a change you are proposing requires a design document, feel free ask us through our mailing list!*
57
58 ## Contributing to Apache Samza
59
60 Samza's code is in an Apache Git repository located [here](https://git-wip-us.apache.org/repos/asf?p=samza.git;a=tree).
61
62 You can check out Samza's code by running:
63
64 ```
65 git clone http://git-wip-us.apache.org/repos/asf/samza.git
66 ```
67
68 The Samza website is built by Jekyll from the markdown files found in the `docs` subdirectory.
69
70 We use Pull Requests to review and discuss your contributions. In order to contribute code, please do the following:
71
72 * If you are working on a big new feature, follow the steps outlined above regarding [design documents](/contribute/design-documents.html) page
73 * 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.
74 * Creating Pull Request
75     1. Fork the Github repository at [http://github.com/apache/samza](http://github.com/apache/samza) if you haven't already 
76     2. Create a new branch in your repository and push your changes to that branch
77         * Make sure you have observed the recommendations in the [coding guide](/contribute/coding-guide.html) and [testing](/contribute/tests.html)
78     3. [Open a Pull Request](https://help.github.com/articles/about-pull-requests/) against the "master" branch of apache/samza
79         * Make sure that the Pull Request title is of the format "SAMZA-&lt;JiraNumber&gt; : &lt;JiraTitle&gt;"
80         * Make sure that your patch cleanly applies against the master branch. If not, rebase before creating the Pull Request
81     4. Change the status of the JIRA to "Patch Available" so that it notifies the committers of the patch being available
82 * Nag us if we don't follow up on your JIRA in a timely fashion.
83 * If your Pull Request is approved, it will automatically be closed, with any associated JIRA when a committer merges your changes. 
84 * If your Pull Request is not approved and requires changes based on reviews, please make changes to your patch. 
85     * While making the changes, kindly update the JIRA status from "Patch Available" to "In Progress". 
86     * 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!
87 * If your Pull Request is rejected for whatever reason, please close it promptly because committers cannot close your Pull Requests!  
88
89 ## For Committers
90
91 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. 
92
93 ### Prepare to merge a Pull Request (PR) by setting up the following:
94
95 1. Setup JIRA on your host
96     * Install Jira packages - ```sudo pip install jira```
97     * 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
98 2. Setup aliases for the remote repositories:‚Äč(Samza Github repo and Apache Samza Repo)
99     * Add ASF git repo for committing the PR
100     ```git remote add samza-apache https://git-wip-us.apache.org/repos/asf/samza.git```
101     * Add Github repo for fetching the patch from the PR
102     ```git remote add samza-github https://github.com/apache/samza.git```
103 3. Set up API tokens for Git
104     * 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)        
105     * Set the created OAuth key as `GITHUB_OAUTH_KEY` environment variable.
106
107 ### Merging a Pull Request
108
109 * 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.
110 ```
111 cd samza
112 ./bin/merge-pull-request.py 
113 ```
114 * Whenever possible, make sure that the commit title includes the JIRA number and title.
115 * Merging changes that don't cleanly apply on the master should be avoided.  
116 * For committers wishing to update the webpage, please see `docs/README.md` for instructions.