Update contribution guidelines (#7)
* Rework README
Restructures the readme to make it easier to read and find the necessary
information.
Drops the instructions on how to use git. If the potential contributor
does not know how to use it, this readme is not the place for them to
learn it.
Removes the entry on committing the generated site artifacts. This
should be done separately to keep the pull requests clean.
Adds links to GitHub resources explaining the basic GitHub workflow.
* Add CONTRIBUTING page
This page will be linked to whenever a new PR is created. It just points
the user to the README and the "Getting Involved" page on the website.
* Update "Get Involved" page
Restructures the sections to make information easier to find.
Adds more information on how to contribute using GitHub.
Adds a section about the need for the Apache Contributor License
Agreement.
Links back to the "Get Involved" page from the "Source Code" page.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..cc9ae4a
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,5 @@
+# Contributing to the JDO site
+
+The general guide on how to contribute to this repository is given in the [README](./README.md#contributing-to-the-site).
+
+If this is your first time contributing to this project, please have a look at our [Get Involved](https://db.apache.org/jdo/get-involved.html) page first.
diff --git a/README.md b/README.md
index c0b7a3a..0c8c0b1 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,20 @@
-# db-jdo-site
-Sources for the Apache DB JDO web site
+# JDO Website
-The website is mirrored under [https://apache.github.io/db-jdo-site/](https://apache.github.io/db-jdo-site/)
+This repository contains the sources for the [Apache DB JDO website](https://db.apache.org/jdo/).
-This repository contains the JDO website source.
-
- * The ASCIIDOC sources can be found in `src/main/asciidoc`
- * The website menu is defined in `src/main/template`
- * The converter for migrating the old html files to asciidoc can be found in `src/main/java`
+The website is mirrored on https://apache.github.io/db-jdo-site/.
+## Building the Site
-How to build the website:
- * Use `git pull` to get the latest version from the repository.
- * Use `git branch MyBranchName` and `git checkout MyBranchName` to create a branch and check it out.
- * Adapt the asciidoc files in `src/main/asciidoc` or the website menu in `src/main/template`
- * Call `mvn clean compile`. This generates html files in `target/site`.
- * Verify the generated website by viewing it locally with a web browser.
- * Commit changes with `git commit -m 'my commit message' `.
- * Push changes to the repository with `git push`.
- * Go to Github.com and create a PR for your branch
- * Once the PR is accepted, the changes should be visible on the website (you may have to refresh the browser).
+The content and styling of the site is defined in the [AsciiDoc](https://asciidoc.org/) format. It is built using [Maven](https://maven.apache.org/).
-How to add javadoc
+The site can be built by calling `mvn clean compile`. This generates the HTML files in `target/site`.
+
+### Adding Javadoc
+
+The site contains a packaged version of the JDO API javadoc. It can be updated as follows:
+
* Create the javadoc jar (e.g. jdo-api-3.2-javadoc.jar) in the db-jdo repository by calling `mvn clean install -Papache-release` in the api submodule.
* Create a new folder under docs e.g. docs/api32.
* Copy the javadocs jar info the new folder: e.g. `cp jdo-api-3.2-javadoc.jar docs/api32`.
@@ -31,5 +23,24 @@
* Edit javadoc.adoc under src/main/asciidoc and create a new section 'JDO 3.2 javadoc'.
* Add two links: one referring index.html in the subfolder and one referring the javadoc jar.
+## Contributing to the Site
+
+Contributions to the website are always appreciated.
+If you are new to this project, please have a look at our [Get Involved](https://db.apache.org/jdo/get-involved.html) page first.
+
+This repository contains the JDO website source.
+
+ * The AsciiDoc sources can be found in `src/main/asciidoc`.
+ * The website menu is defined in `src/main/template`.
+ * The converter for migrating the old HTML files to AsciiDoc can be found in `src/main/java`
+
+Contributions to this repository follow the default [GitHub workflow](https://guides.github.com/introduction/flow/) using [forks](https://guides.github.com/activities/forking/).
+
+To contribute changes, you can follow these steps:
+
+ * Adapt the AsciiDoc files in `src/main/asciidoc` or the website menu in `src/main/template`.
+ * Call `mvn clean compile` to build the site and verify the generated website by viewing it locally with a web browser.
+ * Commit the source changes (not the build artifacts) and open a pull request.
+
### TODO
* If you find any issues please provide a PR or [create a JIRA ticket](https://issues.apache.org/jira/projects/JDO/issues/?filter=allopenissues)
diff --git a/src/main/asciidoc/get-involved.adoc b/src/main/asciidoc/get-involved.adoc
index 3588360..70bfd85 100644
--- a/src/main/asciidoc/get-involved.adoc
+++ b/src/main/asciidoc/get-involved.adoc
@@ -7,42 +7,53 @@
== Get Involvedanchor:Get_Involved[]
-=== How do I contribute, give feedback, fix bugs?
+=== How do I contribute (e.g. give feedback, fix bugs, etc.)?
-The Apache JDO project really needs and appreciates any contributions,
-including documentation help, source code and feedback. Suggested
-changes should come in the form of source code and/or very detailed and
-constructive feedback.
+Apache JDO is run as an open source project, so we always appreciate any contributions, including documentation help, source code, and feedback.
+If you would like to suggest changes, we would appreciate it if they would come in the form of source code and/or constructive feedback.
+
+The default way of providing contributions to this project is through our GitHub page (link:https://github.com/apache/db-jdo[JDO repo], link:https://github.com/apache/db-jdo-site[website repo]).
+We are following the default link:https://guides.github.com/introduction/flow/[GitHub workflow] using link:https://guides.github.com/activities/forking/[forks].
+
+More information on how to access the project source code is available link:source-code.html[here].
+
+
+=== Reporting Bugs
+
+Bugs and other issues can be posted on the project http://issues.apache.org/jira/secure/BrowseProject.jspa?id=10630[JIRA].
+
+
+=== Contacting Us
+
+The project uses different channels of communication:
* Discussion occurs on the link:mail-lists.html[JDO mailing lists].
-* Information on access to the project source code is available
-link:source-code.html[here].
-* Bugs and other issues can be posted on the project
-http://issues.apache.org/jira/secure/BrowseProject.jspa?id=10630[JIRA].
-* Additional documentation and discussion can be found on the project
-http://wiki.apache.org/jdo/[wiki].
-* We have a communications conference call every week. During this call we
-discuss project status, issues, concerns, and strategy. Everyone interested
-in Apache JDO is welcome and encouraged to participate.
-The agenda is available on the Dev List (see link:mail-lists.html[JDO mailing lists]).
+* Additional documentation and discussion can be found on the project http://wiki.apache.org/jdo/[wiki].
+* We have a communications conference call every week.
+ During this call we discuss project status, issues, concerns, and strategy.
+ Everyone interested in Apache JDO is welcome and encouraged to participate.
+ The agenda is available on the Dev List (see link:mail-lists.html[JDO mailing lists]).
-=== How do I become a committer
+=== Contributing as a Non-Committer
-If you're interested in committing to the project:
+In general, contributing to an Apache project requires the contributor signing the link:https://www.apache.org/licenses/contributor-agreements.html[Apache Contributor License Agreement].
+This is, however, only strictly required for "major contributions."
+The boundary for such "major contributions" is not firmly defined, but minor code changes, bug fixes, or documentation changes, for example, should generally not require the signing of the license agreement.
+If you are not sure whether your contribution requires the signing of the license agreement, feel free to ask.
-* You'll need to fill out some legal paperwork and go through a process
-to get an apache committer account: See
-http://apache.org/dev/new-committers-guide.html[New Committers Guide],
-http://apache.org/dev/contributors.html[Contributors], and
-http://apache.org/dev/committers.html[Committers] for more details.
-* After you've received an email from root@apache.org with your
-committer account information, change your initial password: Login by
-'ssh -l <username> people.apache.org'; run 'passwd'; run 'svnpasswd'.
-See http://apache.org/dev/version-control.html[Committer Subversion
-Access].
+
+=== Becoming a Committer
+
+To receive direct push access to the repository, you will have to become an official committer.
+
+If you're interested in becoming a committer:
+
+* You'll need to fill out some legal paperwork and go through a process to get an Apache committer account:
+ See http://apache.org/dev/new-committers-guide.html[New Committers Guide], http://apache.org/dev/contributors.html[Contributors], and http://apache.org/dev/committers.html[Committers] for more details.
+* After you've received an email from root@apache.org with your committer account information, change your initial password:
+ Login by 'ssh -l <username> people.apache.org'; run 'passwd'; run 'svnpasswd'.
+ See http://apache.org/dev/version-control.html[Committer Subversion Access].
* Check out the JDO sources and test your svn account:
-http://svn.apache.org/viewcvs.cgi/db/jdo/[SubversionRepository].
-* Sign up for a http://wiki.apache.org/jdo/UserPreferences[WiKi]
-account.
+ http://svn.apache.org/viewcvs.cgi/db/jdo/[Subversion Repository].
+* Sign up for a http://wiki.apache.org/jdo/UserPreferences[Wiki] account.
* Sign up for an http://issues.apache.org/jira/[ASF JIRA] account.
-
diff --git a/src/main/asciidoc/source-code.adoc b/src/main/asciidoc/source-code.adoc
index 25327b1..b79c8ad 100644
--- a/src/main/asciidoc/source-code.adoc
+++ b/src/main/asciidoc/source-code.adoc
@@ -26,9 +26,9 @@
git clone https://github.com/apache/db-jdo.git
....
-Contributors can fork this repo using github’s tools and contribute patches/new features using pull requests.
+Contributors can fork this repo using GitHub’s tools and contribute patches/new features using pull requests. See link:get-involved.html#_how_do_i_contribute_e_g_give_feedback_fix_bugs_etc[Getting Involved].
-Committers can push to this repo directly, once their ASF account and github account have been linked.
+Committers can push to this repo directly, once their ASF account and GitHub account have been linked.
See https://gitbox.apache.org/setup[gitbox setup] for more details on how to do this.
=== Web Site
