You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by he...@apache.org on 2015/09/04 15:30:29 UTC
[06/15] incubator-brooklyn git commit: tidy up contribute-docs page,
and minor tidies elsewhere in docs
tidy up contribute-docs page, and minor tidies elsewhere in docs
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/27757c3d
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/27757c3d
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/27757c3d
Branch: refs/heads/master
Commit: 27757c3de80034d910bb8bf4087c96da1681c411
Parents: 1760fd6
Author: Alex Heneveld <al...@cloudsoft.io>
Authored: Thu Sep 3 03:16:39 2015 +0100
Committer: Alex Heneveld <al...@cloudsoft.io>
Committed: Thu Sep 3 12:15:57 2015 +0100
----------------------------------------------------------------------
.../website/community/how-to-contribute-docs.md | 163 ++++---------------
.../release-process/release-version.md | 5 +-
docs/website/meta/versions.md | 12 +-
3 files changed, 39 insertions(+), 141 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/27757c3d/docs/website/community/how-to-contribute-docs.md
----------------------------------------------------------------------
diff --git a/docs/website/community/how-to-contribute-docs.md b/docs/website/community/how-to-contribute-docs.md
index eda9597..0da9b3b 100644
--- a/docs/website/community/how-to-contribute-docs.md
+++ b/docs/website/community/how-to-contribute-docs.md
@@ -1,153 +1,60 @@
---
layout: website-normal
-title: How to Contribute Documentation
+title: Contributing Documentation
navgroup: community
---
-<!-- TODO do we want this page? can be simplified a lot since the process is identical as for how-to-contribute,
- with the exception of the "Edit this Page" (and reminder we can accept small changes without CLA or Jira);
- we could promote much of the content from README.md to here... -->
-
-
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 docs live in the **docs** project in the Brooklyn codebase,
-built using standard jekyll/markdown with a few extensions.
-
-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 guide.
- Content for this is in the `website` directory.
-
-- **Version-specific user guide**. These pages have a URL with a path that
- begins /v/*version-number*: for example,
- https://brooklyn.incubator.apache.org/v/0.9.0-SNAPSHOT and {% comment %}BROOKLYN_VERSION{% endcomment %}
- the special *latest* set at https://brooklyn.incubator.apache.org/v/latest .
- Content for this is in the `guide` directory.
-
+Quick Edits
+-----------
-Contributor license agreement
------------------------------
+The easiest way to contribute improvements to the doc is with the *Edit this page*
+button at the bottom of most pages. This will take you to the GitHub repository where
+you can immediately begin editing the file.
-Apache Brooklyn is licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). All
-contributions will be under this license, so please read and understand this license before contributing.
-
-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](https://www.apache.org/licenses/#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](https://issues.apache.org/jira/browse/BROOKLYN)
-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
+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.
+(You will need a GitHub account but this is free and easy to create.)
-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
-change.
+Once you have made your edits:
-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.
+* In the 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.
+* Next click *Propose file change* to prepare a pull request
+* Finally click *Create pull request* to notify the team of your proposed change.
+ The community will review it and merge and update the web site as necessary.
-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
-[https://github.com/apache/incubator-brooklyn](https://github.com/apache/incubator-brooklyn)
-
-Your commit messages must properly describe the changes that have been made and
-their purpose ([here are some
-guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)).
-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
-one).
-
-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](https://help.github.com/articles/set-up-git)
-- [Forking a Repository](https://help.github.com/articles/fork-a-repo)
-- [Submitting Pull Requests](https://help.github.com/articles/using-pull-requests)
-- [Rebasing your Branch](https://help.github.com/articles/interactive-rebase)
-
-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 least 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.
+Bigger Contributions
+--------------------
+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.
-### Contributing without using GitHub
+For this, you should first review the general tips on [How to Contribute](../developers/how-to-contribute.md).
-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
-`https://git-wip-us.apache.org/repos/asf/incubator-brooklyn.git`; for example:
+Next, you’ll want to become familiar with the `docs/` folder in the Brooklyn codebase where the docs live.
+In particular, note that the Brooklyn documentation is split into two parts:
- $ git clone https://git-wip-us.apache.org/repos/asf/incubator-brooklyn.git
+- **The main website and shared documentation**. This covers the root website
+ and all pages that are not part of the version-specific user guide.
+ Content for this is in the `website` directory.
+
+- **Version-specific user guide**. These pages have a URL with a path that
+ begins /v/*version-number*: for example,
+ https://brooklyn.incubator.apache.org/v/0.8.0-incubating and {% comment %}BROOKLYN_VERSION{% endcomment %}
+ the special *latest* set at https://brooklyn.incubator.apache.org/v/latest. Content for this is in the `guide` directory.
-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.
+The main user guide shown on this site is for the most recent stable version,
+currently {{ site.brooklyn-stable-version }}.
+Guides for other versions are available [here](../meta/versions.md).
For More Information
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/27757c3d/docs/website/developers/committers/release-process/release-version.md
----------------------------------------------------------------------
diff --git a/docs/website/developers/committers/release-process/release-version.md b/docs/website/developers/committers/release-process/release-version.md
index e43868b..eea6943 100644
--- a/docs/website/developers/committers/release-process/release-version.md
+++ b/docs/website/developers/committers/release-process/release-version.md
@@ -32,9 +32,7 @@ git checkout -b $VERSION_NAME
git push -u apache $VERSION_NAME
{% endhighlight %}
-Now change the version numbers throughout the repository using the script `release/change-version.sh`.
-
-Example:
+Now change the version numbers in this branch throughout the project using the script `release/change-version.sh` and commit it:
{% highlight bash %}
./release/change-version.sh BROOKLYN $OLD_MASTER_VERSION $VERSION_NAME
@@ -45,6 +43,7 @@ git push
{% endhighlight %}
+
Update the version on master
----------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/27757c3d/docs/website/meta/versions.md
----------------------------------------------------------------------
diff --git a/docs/website/meta/versions.md b/docs/website/meta/versions.md
index e178770..0cca91c 100644
--- a/docs/website/meta/versions.md
+++ b/docs/website/meta/versions.md
@@ -18,17 +18,9 @@ This documentation was generated {{ site.time | date_to_string }}.
Apache Brooklyn has made the following releases:
-* **0.7.0-incubating**: New policies, more clouds, improved Windows support and many other improvements. Apache-endorsed binary release! (July 2015)
- * [User guide](/v/0.7.0-incubating/), download via mirrors
- «<a href="https://www.apache.org/dyn/closer.cgi/incubator/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.tar.gz">bin.tar.gz</a>»
- «<a href="https://www.apache.org/dyn/closer.cgi/incubator/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-bin.zip">bin.zip</a>»
- «<a href="https://www.apache.org/dyn/closer.cgi/incubator/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.tar.gz">src.tar.gz</a>»
- «<a href="https://www.apache.org/dyn/closer.cgi/incubator/brooklyn/apache-brooklyn-0.7.0-incubating/apache-brooklyn-0.7.0-incubating-src.zip">src.zip</a>»
-
-* **0.7.0-M2-incubating**: YAML, persistence, Chef, Windows, Docker. The first Apache release! (December 2014)
- * [User guide](/v/0.7.0-M2-incubating/), download via mirrors
- «<a href="https://www.apache.org/dyn/closer.cgi/incubator/brooklyn/0.7.0-M2-incubating/apache-brooklyn-0.7.0-M2-incubating.tar.gz">src.tar.gz</a>»
+* **[0.7.0-incubating](/v/0.7.0-incubating/)**: New policies, more clouds, improved Windows support and many other improvements. Apache-endorsed binary release! (July 2015)
+* **[0.7.0-M2-incubating](/v/0.7.0-M2-incubating/)**: YAML, persistence, Chef, Windows, Docker. The first Apache release! (December 2014)
Note: These "Version History" links are to permanent versions in the archive,
different to the "Current Version" links.