You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2012/12/18 20:51:50 UTC
svn commit: r1423605 - in /isis/site/trunk/content: contributors/about.md
contributors/building-isis.md contributors/coding-conventions.md
contributors/development-environment.md contributors/verifying-releases.md
documentation.md
Author: danhaywood
Date: Tue Dec 18 19:51:49 2012
New Revision: 1423605
URL: http://svn.apache.org/viewvc?rev=1423605&view=rev
Log:
isis site; stuff on building isis, dev env and on verifying releases
Added:
isis/site/trunk/content/contributors/building-isis.md
- copied, changed from r1419364, isis/site/trunk/content/contributors/coding-conventions.md
Removed:
isis/site/trunk/content/contributors/coding-conventions.md
Modified:
isis/site/trunk/content/contributors/about.md
isis/site/trunk/content/contributors/development-environment.md
isis/site/trunk/content/contributors/verifying-releases.md
isis/site/trunk/content/documentation.md
Modified: isis/site/trunk/content/contributors/about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/about.md?rev=1423605&r1=1423604&r2=1423605&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/about.md (original)
+++ isis/site/trunk/content/contributors/about.md Tue Dec 18 19:51:49 2012
@@ -4,9 +4,9 @@ Title: Contributors
- [Contributing](contributing.html)
- [Development Environment](development-environment.html)
+- [Building Isis](building-isis.html)
- [Git Policy](git-policy.html)
- [Git Cookbook](git-cookbook.html)
-- [Coding Conventions](coding-conventions.html)
- [Versioning Policy](versioning-policy.html)
### Committers
Copied: isis/site/trunk/content/contributors/building-isis.md (from r1419364, isis/site/trunk/content/contributors/coding-conventions.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/building-isis.md?p2=isis/site/trunk/content/contributors/building-isis.md&p1=isis/site/trunk/content/contributors/coding-conventions.md&r1=1419364&r2=1423605&rev=1423605&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/coding-conventions.md (original)
+++ isis/site/trunk/content/contributors/building-isis.md Tue Dec 18 19:51:49 2012
@@ -1,25 +1,51 @@
-Title: Coding Conventions
+Title: Building Isis
-Code should be formatted using the following Eclipse templates:
+Isis is build using Maven; details of setting up your development environment can be found [here](development-environment.html).
-- `Windows > Preferences > Java > Code Style > Code Templates`
- - Import [Apache-code-style-template.xml](resources/Apache-code-style-template.xml)
-- `Windows > Preferences > Java > Code Style > Formatter`
- - Import [Apache-code-style-formatting.xml](resources/Apache-code-style-formatting.xml)
-- `Windows > Preferences > Java > Code Style > Organize Imports`
- - Import [isis.importorder](resources/isis.importorder)
-- `Windows > Preferences > Java > Code Style > Clean Up`
- - Import [Apache-Isis-code-style-cleanup.xml](resources/Apache-Isis-code-style-cleanup.xml)
- - (this performs both code formatting and organizing imports)
-
-In addition, you will probably want to import the Java editor templates, as described in the [getting started](../getting-started/editor-templates.html) section.
-<!--
-TODO: to add from the original incubator website [here](http://incubator.apache.org/isis "Apache Isis (incubator website)").
-
-In addition:
-
-- checkstyle, as per sec.Checkstyle
-- PMD, as per sec.PMD
-- findbugs, as per sec.FindBugs
--->
+###Building all of Isis
+To build the source code from the command line, simply go to the root directory and type:
+<pre>
+mvn clean install
+</pre>
+
+The first time you do this, you'll find it takes a while since Maven needs to download all of the Isis prerequisites.
+
+Thereafter you can speed up the build by adding the `-o` (offline flag):
+
+<pre>
+mvn clean install -o
+</pre>
+
+For the most part, though, you may want to rely on an IDE such as Eclipse to build the codebase for you. Both Eclipse and Idea (12.0+) support incremental background compilation.
+
+When using Eclipse, a Maven profile is configured such that Eclipse compiles to `target-ide` directory rather than the usual `target` directory. You can therefore switch between Eclipse and Maven command line without one interfering with the other.
+
+###Building an Individual Component of Isis
+
+Alternatively, you can go to the root of any of the components and build each individually.
+
+For example:
+
+* to build just core, use:
+
+<pre>
+ cd core
+ mvn clean install
+</pre>
+
+* to build the JDO objectstore, use:
+
+<pre>
+ cd component/objectstore/jdo
+ mvn clean install
+</pre>
+
+* to build the Wicket viewer, use:
+
+<pre>
+ cd component/viewer/wicket
+ mvn clean install
+</pre>
+
+A list of all of the Isis components can be found in our [release process](release-process.html) documentation.
\ No newline at end of file
Modified: isis/site/trunk/content/contributors/development-environment.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/development-environment.md?rev=1423605&r1=1423604&r2=1423605&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/development-environment.md (original)
+++ isis/site/trunk/content/contributors/development-environment.md Tue Dec 18 19:51:49 2012
@@ -1,48 +1,39 @@
Title: Development Environment
-#### Installing Git
+## Git
+
+The Isis source code lives in a git repo.
+
+### Installation
The easiest place to get hold of command-line git is probably the [github download page](http://git-scm.com/downloads).
On Windows, this also installs the rather good mSysGit Unix shell. We recommend that you enable git for both the mSysgit and the Windows command prompt:
-<img src="resources/setting-up-git.png" width="400px"></img>
+<img src="resources/setting-up-git.png" width="350px"></img>
Once git is installed, the two main command line tools to note are:
- `git` command line tool
- `gitk` for viewing the commit history
-Three commands in particular worth knowing:
-
-<pre>git help <i>command</i></pre>
-
- will open the man page in your web browser
-
-<pre>git gui</pre>
-
- will open up a basic GUI client to staging changes and making commits
-
-<pre>gitk --all</pre>
-
- will open the commit history for all branches. In particular, you should be able to see the local `master`, which branch you are working on (the `HEAD`), and also the last known position of the `master` branch from the central repo, called `origin/master`.
-
If using Windows, note that github also have a dedicated [Windows client](https://help.github.com/articles/set-up-git). With a little [hacking around](http://haacked.com/archive/2012/05/30/using-github-for-windows-with-non-github-repositories.aspx), it can also be made to work with non-github repositories.
If using Mac, you might also want to check out Atlassian's [Sourcetree](http://www.atlassian.com/software/sourcetree/overview).
-
#### Cloning the Isis repo and Configuring
-First, clone the Isis repo. If you are **not a committer**, please see the [contributing](contributing.html) page for details on which repo to clone from.
+First, clone the Isis repo.
-**Committers**, meanwhile, should clone from the Apache read/write repo:
+If you are a **committer**, then clone from the Apache read/write repo:
<pre>
git clone https://git-wip-us.apache.org/repos/asf/isis.git
</pre>
+If you are **not a committer**, please see the [contributing](contributing.html) page for details on which repo to clone from.
+
You should then configure your user name and password; see also [Apache's git](https://git-wip-us.apache.org/) docs:
<pre>
@@ -78,6 +69,23 @@ git config branch.autosetuprebase always
If you don't use git outside of Apache, you can add the `--global` flag so that the above settings apply for all repos managed by git on your PC.
+### Getting help
+
+Three commands of git that in particular worth knowing:
+
+<pre>git help <i>command</i></pre>
+
+ will open the man page in your web browser
+
+<pre>git gui</pre>
+
+ will open up a basic GUI client to staging changes and making commits
+
+<pre>gitk --all</pre>
+
+ will open the commit history for all branches. In particular, you should be able to see the local `master`, which branch you are working on (the `HEAD`), and also the last known position of the `master` branch from the central repo, called `origin/master`.
+
+
For further reading, see:
- [git config man page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html)
@@ -95,22 +103,63 @@ Set `MAVEN_OPTS` environment variable:
MAVEN_OPTS=-Xms512m -Xmx1024m -XX:MaxPermSize=128m
</pre>
+## Installing and Configuring Eclipse
+You can use any IDE to work with Isis, but most of the Isis committers tend to use Eclipse.
-<!--
-TODO: x-ref importing-projects
-TODO: x-ref sharing projects
--->
+Make sure you are using a version of Eclipse that includes both the `m2e` feature (Maven integration) and the `eGit` feature (Git integration). Both 3.8 (2011) and 4.2 (2012) have these features bundled as part of the Java and JEE editions; or you can always install using `Help > Install New Software`.
+### Importing Projects
+Next thing to do is to import the Isis projects into your workspace. This is done using `File > Import >Project`:
+<img src="resources/importing-projects-1.png" width="500px"></img>
-## Building the Source Code
+On the next page, specify the root directory where you cloned the Isis repo. Eclipse will recursively find all the projects that make up Isis:
-To build the source code, simply go to the root directory and type:
+<img src="resources/importing-projects-2.png" width="500px"></img>
-<pre>
-mvn clean install
-</pre>
+Hit `Finish`; Eclipse should automatically build the entire codebase.
+
+### Sharing Projects
+
+The next thing to do is to configure eGit so that you can use git commands within Eclipse. This is done by selecting all the projects in the `Package Explorer`, then right clicking `Team > Share Project`:
+
+<img src="resources/sharing-projects-1.png" width="500px"></img>
+
+On the next page, choose the `Use or create repository in parent folder of project` checkbox:
+
+<img src="resources/sharing-projects-2.png" width="500px"></img>
+
+Hit `Finish` and you are done.
+
+### Coding Conventions
+
+Isis provides a number of Eclipse templates to help ensure that code is formatted according to our standards:
+
+- `Windows > Preferences > Java > Code Style > Code Templates`
+ - Import [Apache-code-style-template.xml](resources/Apache-code-style-template.xml)
+- `Windows > Preferences > Java > Code Style > Formatter`
+ - Import [Apache-code-style-formatting.xml](resources/Apache-code-style-formatting.xml)
+- `Windows > Preferences > Java > Code Style > Organize Imports`
+ - Import [isis.importorder](resources/isis.importorder)
+- `Windows > Preferences > Java > Code Style > Clean Up`
+ - Import [Apache-Isis-code-style-cleanup.xml](resources/Apache-Isis-code-style-cleanup.xml)
+ - (this performs both code formatting and organizing imports)
+
+In addition, you will probably want to import the Java editor templates, as described in the [getting started](../getting-started/editor-templates.html) section.
+
+<!--
+TODO: to add from the original incubator website [here](http://incubator.apache.org/isis "Apache Isis (incubator website)").
+
+In addition:
+
+- checkstyle, as per sec.Checkstyle
+- PMD, as per sec.PMD
+- findbugs, as per sec.FindBugs
+-->
+
+
+## What's Next
-Alternatively, you can go to the root of any of the components (eg as documented [here](release-process.html) and build each individually.
\ No newline at end of file
+The next thing to do is probably to build Isis; see [here](building-isis.html).
Modified: isis/site/trunk/content/contributors/verifying-releases.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/contributors/verifying-releases.md?rev=1423605&r1=1423604&r2=1423605&view=diff
==============================================================================
--- isis/site/trunk/content/contributors/verifying-releases.md (original)
+++ isis/site/trunk/content/contributors/verifying-releases.md Tue Dec 18 19:51:49 2012
@@ -4,6 +4,15 @@ Whenever a committer announces a vote on
This page provides some guidance on what a voter is expected to verify before casting their vote.
+Per this [ASF documentation](http://www.apache.org/dev/release.html), the legal requirements for an ASF release are:
+
+* a source zip file + corresponding signature (signed by me, which is in the ASF web of trust and in our KEYS file)
+* all source files have the Apache license (this is ensured by the running of the rat plugin prior to release; you could run it on the unzipped source)
+* all dependencies are appropriately licensed; see the DEPENDENCIES file which is automatically generated from the POMs plus the supplemental-models.xml file
+
+Note that the binaries are *not* an ASF release, they merely exist on the Maven central repo as a convenience.
+
+
## Verifying the source release artifacts
Download both the ZIP and .ASC files from the location specified in the voting email. To verify that the signature is correct, use:
Modified: isis/site/trunk/content/documentation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/documentation.md?rev=1423605&r1=1423604&r2=1423605&view=diff
==============================================================================
--- isis/site/trunk/content/documentation.md (original)
+++ isis/site/trunk/content/documentation.md Tue Dec 18 19:51:49 2012
@@ -46,9 +46,9 @@ Title: Documentation
- [Contributing](contributors/contributing.html)
- [Development Environment](contributors/development-environment.html)
+- [Building Isis](contributors/building-isis.html)
- [Git Policy](contributors/git-policy.html)
- [Git Cookbook](contributors/git-cookbook.html)
-- [Coding Conventions](contributors/coding-conventions.html)
- [Versioning Policy](contributors/versioning-policy.html)
### Committers