brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [5/6] git commit: Add community/
Date Mon, 30 Jun 2014 09:15:42 GMT
Add community/


Branch: refs/heads/master
Commit: 842d2f3182336631e0327fca330d83207b5ba09e
Parents: c4c6c45
Author: Richard Downer <>
Authored: Mon Jun 30 10:02:50 2014 +0100
Committer: Richard Downer <>
Committed: Mon Jun 30 10:02:50 2014 +0100

 community/ | 140 +++++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)
diff --git a/community/ b/community/
new file mode 100644
index 0000000..ceb3c70
--- /dev/null
+++ b/community/
@@ -0,0 +1,140 @@
+layout: normal
+title: How to contribute documentation
+navgroup: community
+Welcome and thank you for your interest in contributing to Apache Brooklyn! This guide will
take you through the
+process of making contributions to the Apache Brooklyn website and documentation.
+Two types of documentation
+The Brooklyn documentation is split into two parts:
+- **The main website and shared documentation**. This covers the root website
+  and all pages that are not part of the version-specific user manual. This
+  guide describes how to work with this documentation.
+- **Version-specific user manual**. These pages have a URL with a path that
+  begins /v/*version-number* - for example,
+ This documentation is part
+  of the main source code, so please refer to the [How to contribute source
+  code](how-to-contribute.html) for help with modifying these pages.
+Contributor license agreement
+Apache Brooklyn is licensed under the [Apache License, Version 2.0](
+contributions will be under this license, so please read and understand this license before
+For all but the most trivial patches, you are required to file a Contributor License Agreement
with the Apache
+Software Foundation. Please read the [guide to CLAs](
to find out how to file a
+CLA with the Foundation.
+Before you start
+### Join the community
+If it's your first contribution or it's a particularly big or complex contribution, things
typically go much more
+smoothly when they start off with a conversation. Visit our [Community](index.html) page
to see how you can contact
+us via IRC or email.
+### Create an issue in Jira
+Your first step is to create or find an issue in [Brooklyn's Jira](
+for your feature request or fix. For small changes this isn't necessary, but it's good to
see if your change fixes an
+existing issue anyway.
+Contributing using *Edit this page*
+Most of the pages on the website have an *Edit this page* button at the bottom.
+Clicking this button will take you to the GitHub repository and immediately
+begin editing the file. This approach makes editing easy, as you do not need to
+clone the repository to your workstation and make changes there; they can be
+changed directly on the GitHub website for the repository.
+Once you have made your edits, there is a short form titled *Propose file
+change*. Provide a short description of the change in the first box; optionally,
+provide a longer description in the second box. If your change fixes or
+addresses a Jira issue, be sure to mention it. Finally, click the *Propose file
+change* button to prepare a pull request, and then *Create pull request* to
+formally submit your change request and notify the dev team of your proposed
+The website is not a Wiki and your changes will not appear immediately. The
+community mailing list will receive a notification of your proposed change, and
+an Apache Brooklyn committer will review your changes. Once your change has
+passed review, the committer will merge it and re-publish the public website.
+While the *Edit this page* button is great for quickly editing a single page, if
+you want to do anything that involves editing multiple pages, you will need to
+fork and clone the repository and make the changes on your own workstation - see
+the next section for information on this.
+Contributing using GitHub
+Our GitHub repository is located at
+Your commit messages must properly describes the changes that have been made and
+their purpose ([here are some
+If your contributions fix a Jira issue, then ensure that you reference the issue
+(like `BROOKLYN-9876`) in the commit message.
+Create a pull request (PR) in GitHub for the change you're interested in making.
+The comment section of the PR must contain a link to the Jira issue (if it has
+Some good references for working with GitHub are below.  We ask that you keep
+your change rebased to master as much as possible, and we will ask you to rebase
+again if master has moved before accepting your patch.
+- [Setting Up Git with GitHub](
+- [Forking a Repository](
+- [Submitting Pull Requests](
+- [Rebasing your Branch](
+Finally, add a comment in the Jira issue with a link to the pull request so we
+know the code is ready to be reviewed.
+### Reviews
+The Apache Brooklyn community will review your pull request before it is merged.
+This process can take a while, so please be patient. If we are slow to respond,
+please feel free to post a reminder to the PR, Jira issue, IRC channel or
+mailing list - see the [Community](index.html) page to see how to contact us.
+During the review process you may be asked to make some changes to your
+submission. While working through feedback, it can be beneficial to create new
+commits so the incremental change is obvious.  This can also lead to a complex
+set of commits, and having an atomic change per commit is preferred in the end.
+Use your best judgement and work with your reviewer as to when you should revise
+a commit or create a new one.
+A pull request is considered ready to be merged once it gets at lease one +1
+from a committer. Once all the changes have been completed and the pull request
+is accepted, you may be asked to rebase it against the latest code. You may also
+wish to squash some commits together and make other history revisions, to leave
+the commit history clean and easily understood.
+### Contributing without using GitHub
+If you prefer to not use GitHub, then that is fine - we are also happy to accept
+patches attached to a Jira issue.  Our canonical repository is located at
+``; for example:
+    $ git clone
+When producing patches, please use `git format-patch` or a similar mechanism -
+this will ensure that you are properly attributed as the author of the patch
+when a committer merges it.

View raw message