From commits-return-13513-archive-asf-public=cust-asf.ponee.io@pulsar.incubator.apache.org Tue Aug 28 15:14:03 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id 62312180674 for ; Tue, 28 Aug 2018 15:14:02 +0200 (CEST) Received: (qmail 76658 invoked by uid 500); 28 Aug 2018 13:14:01 -0000 Mailing-List: contact commits-help@pulsar.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@pulsar.incubator.apache.org Delivered-To: mailing list commits@pulsar.incubator.apache.org Received: (qmail 76649 invoked by uid 99); 28 Aug 2018 13:14:01 -0000 Received: from ec2-52-202-80-70.compute-1.amazonaws.com (HELO gitbox.apache.org) (52.202.80.70) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 28 Aug 2018 13:14:01 +0000 From: GitBox To: commits@pulsar.apache.org Subject: [GitHub] maskit commented on a change in pull request #2459: Added Contributing page on website Message-ID: <153546204097.5335.9416550712217568825.gitbox@gitbox.apache.org> Date: Tue, 28 Aug 2018 13:14:00 -0000 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit maskit commented on a change in pull request #2459: Added Contributing page on website URL: https://github.com/apache/incubator-pulsar/pull/2459#discussion_r213307395 ########## File path: site2/website/contributing.md ########## @@ -0,0 +1,250 @@ + +The Apache Pulsar community welcomes contributions from anyone with a passion for distributed systems! Pulsar has many different opportunities for contributions -- +write new examples/tutorials, add new user-facing libraries, write new Pulsar IO connectors, or participate on the documentation effort. + +We use a review-then-commit workflow in Pulsar for all contributions. + +**For larger contributions or those that affect multiple components:** + +1. **Engage**: We encourage you to work with the Pulsar community on the + [Github Issues](https://github.com/apache/incubator-pulsar/issues) and + [developer’s mailing list](/contact) to identify + good areas for contribution. +1. **Design:** More complicated contributions will likely benefit from some early discussion in + order to scope and design them well. + +**For all contributions:** + +1. **Code:** The best part ;-) +1. **Review:** Submit a pull request with your contribution to our + [GitHub Repo](https://github.com/apache/incubator-pulsar). Work with a committer to review and + iterate on the code, if needed. +1. **Commit:** Once at least 2 Pulsar committers have approved the pull request, a Pulsar committer + will merge it into the master branch (and potentially backport to stable branches in case of + bug fixes). + +We look forward to working with you! + +## Engage + +### Mailing list(s) + +We discuss design and implementation issues on the [dev@pulsar.incubator.apache.org](mailto:dev@pulsar.incubator.apache.org) +mailing list, which is archived [here](https://lists.apache.org/list.html?dev@pulsar.apache.org). +Join by emailing [`dev-subscribe@pulsar.incubator.apache.org`](mailto:dev-subscribe@pulsar.incubator.apache.org). + +If interested, you can also join the other [mailing lists](/contact). + +### Github Issues + +We are using [Github Issues](https://github.com/apache/incubator-pulsar/issues) as the issue tracking +and project management tool, as well as a way to communicate among a very diverse and distributed set +of contributors. To be able to gather feedback, avoid frustration, and avoid duplicated efforts all +Pulsar related work are being tracked there. + +If you do not already have an Github account, sign up [here](https://github.com/join). + +If a quick [search](https://github.com/apache/incubator-pulsar/issues) doesn’t turn up an existing +Github issue for the work you want to contribute, create it. Please discuss your idea with a +committer in Github or, alternatively, on the developer mailing list. + +If there’s an existing Github issue for your intended contribution, please comment about your intended +work. Once the work is understood, a committer will assign the issue to you. If an issue is currently +assigned, please check with the current assignee before reassigning. + +For moderate or large contributions, you should not start coding or writing a design document unless +there is a corresponding Github issue assigned to you for that work. Simple changes, like fixing typos, +do not require an associated issue. + +### Online discussions + +We are using [Apache Pulsar Slack channel](https://apache-pulsar.slack.com/) for online discussions. +You can self-invite yourself by accessing [this link](https://apache-pulsar.herokuapp.com/). + +Slack channels are great for quick questions or discussions on specialized topics. Remember that we +strongly encourage communication via the mailing lists, and we prefer to discuss more complex subjects +by email. Developers should be careful to move or duplicate all the official or useful discussions to +the issue tracking system and/or the dev mailing list. + +## Design + +To avoid potential frustration during the code review cycle, we encourage you to clearly scope and +design non-trivial contributions with the Pulsar community before you start coding. + +We are using "Pulsar Improvement Proposals" (or "PIP") for managing major changes to Pulsar. The +list of all PIPs is maintained in the Pulsar wiki at https://github.com/apache/incubator-pulsar/wiki. + +## Code + +To contribute code to Apache Pulsar, you’ll have to do a few administrative steps once, and then +follow the [Coding Guide](../coding_guide). + +### One-time Setup + +#### [Optionally] Submit Contributor License Agreement + +Apache Software Foundation (ASF) desires that all contributors of ideas, code, or documentation to the Apache projects complete, sign, and submit an [Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf) (ICLA). The purpose of this agreement is to clearly define the terms under which intellectual property has been contributed to the ASF and thereby allow us to defend the project should there be a legal dispute regarding the software at some future time. + +We require you to have an ICLA on file with the Apache Secretary for larger contributions only. For smaller ones, however, we rely on [clause five](http://www.apache.org/licenses/LICENSE-2.0#contributions) of the Apache License, Version 2.0, describing licensing of intentionally submitted contributions and do not require an ICLA in that case. + +#### Obtain a GitHub account + +We use GitHub’s pull request functionality to review proposed code changes. + +If you do not already have a personal GitHub account, sign up [here](https://github.com/join). + +#### Fork the repository on GitHub + +Go to the [Pulsar GitHub Repo](https://github.com/apache/incubator-pulsar/) and fork the repository +to your own private account. This will be your private workspace for staging changes. + +#### Clone the repository locally + +You are now ready to create the development environment on your local machine. Feel free to repeat +these steps on all machines that you want to use for development. + +We assume you are using SSH-based authentication with GitHub. If necessary, exchange SSH keys with +GitHub by following [their instructions](https://help.github.com/articles/generating-an-ssh-key/). + +Clone your personal Pulsar’s GitHub fork. + + $ git clone https://github.com//incubator-pulsar.git + $ cd incubator-pulsar + +Add Apache Repo as additional Git remotes, where you can sync the changes (for committers, you need +these two remotes for pushing changes). + + $ git remote add apache https://github.com/apache/incubator-pulsar + +You are now ready to start developing! + +#### [Optional] IDE Setup + +Depending on your preferred development environment, you may need to prepare it to develop Pulsar code. + +##### IntelliJ + +###### Enable Annotation Processing + +To configure annotation processing in IntelliJ: + +1. Open Annotation Processors Settings dialog box by going to Settings -> Build, Execution, Deployment -> Compiler -> Annotation Processors. +1. Select the following buttons: + 1. "Enable annotation processing" + 1. "Obtain processors from project classpath" + 1. "Store generated sources relative to: Module content root" +1. Set the generated source directories to be equal to the Maven directories: + 1. Set "Production sources directory:" to "target/generated-sources/annotations". + 1. Set "Test sources directory:" to "target/generated-test-sources/test-annotations". +1. Click "OK". + +##### Eclipse + +Use a recent Eclipse version that includes m2e. Currently we recommend Eclipse Neon. +Start Eclipse with a fresh workspace in a separate directory from your checkout. + +###### Initial setup + +1. Import the Pulsar projects + + File + -> Import... + -> Existing Maven Projects + -> Browse to the directory you cloned into and select "pulsar" + -> make sure all pulsar projects are selected + -> Finalize + +You now should have all the Pulsar projects imported into eclipse and should see no compile errors. + +### Create a branch in your fork + +You’ll work on your contribution in a branch in your own (forked) repository. Create a local branch, initialized with the state of the branch you expect your changes to be merged into. Keep in mind that we use several branches, including `master`, feature-specific, and release-specific branches. If you are unsure, initialize with the state of the `master` branch. + + $ git fetch apache + $ git checkout -b apache/master + +At this point, you can start making and committing changes to this branch in a standard way. + +### Syncing and pushing your branch + +Periodically while you work, and certainly before submitting a pull request, you should update your branch with the most recent changes to the target branch. + + $ git pull --rebase + +Remember to always use `--rebase` parameter to avoid extraneous merge commits. + +Then you can push your local, committed changes to your (forked) repository on GitHub. Since rebase may change that branch's history, you may need to force push. You'll run: + + $ git push --force + +### Testing + +All code should have appropriate unit testing coverage. New code should have new tests in the same contribution. Bug fixes should include a regression test to prevent the issue from reoccurring. + +## Review + +Once the initial code is complete and the tests pass, it’s time to start the code review process. We review and discuss all code, no matter who authors it. It’s a great way to build community, since you can learn from other developers, and they become familiar with your contribution. It also builds a strong project by encouraging a high quality bar and keeping code consistent throughout the project. + +### Create a pull request + +Organize your commits to make a committer’s job easier when reviewing. Committers normally prefer multiple small pull requests, instead of a single large pull request. Within a pull request, a relatively small number of commits that break the problem into logical steps is preferred. For most pull requests, you'll squash your changes down to 1 commit. You can use the following command to re-order, squash, edit, or change description of individual commits. + + $ git rebase -i apache/master + +You'll then push to your branch on GitHub. Note: when updating your commit after pull request feedback and use squash to get back to one commit, you will need to do a force submit to the branch on your repo. + +Navigate to the [Pulsar GitHub Repo](https://github.com/apache/incubator-pulsar) to create a pull request. The title of the pull request should be strictly in the following format: Review comment: > Simple changes, like fixing typos, do not require an associated issue. v.s. > The title of the pull request should be strictly in the following format: Issue Perhaps it'd be better to add "if/unless ...". ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: users@infra.apache.org With regards, Apache Git Services