Merge pull request #5 from martin-g/update-build-steps
Update build steps in README and Get Involved page
diff --git a/README.txt b/README.md
similarity index 69%
rename from README.txt
rename to README.md
index 2374a79..79f4a9b 100644
--- a/README.txt
+++ b/README.md
@@ -1,4 +1,4 @@
-Note: the branch trnk is obsolete. Please use the master branch.
+Note: the branch trunk is obsolete. Please use the master branch.
----
The Apache Velocity Project
@@ -15,59 +15,60 @@
http://velocity.apache.org/ (our homepage). It is the envelope site for all Apache
Velocity sub projects.
- In short: This svn repository is only interesting for you if you
+ In short: This Git repository is only interesting for you if you
a) want to re-create the Apache Velocity site on your local computer or intranet.
- b) are an Apache Velocity committer and want to update the site.
+ b) are an Apache Velocity committer/contributor and want to update the site.
Building the Site
-----------------
- Apache Velocity uses Apache Maven 2 to build the site.
+ Apache Velocity uses [Apache Content Management System](http://www.apache.org/dev/cms.html) to build the site.
+ The whole process of buiding the site is automated with a Docker based build [script](./builder/bin/builder.sh).
- It requires at least Maven 2.0.5 to build, Maven 2.0.6 is recommended.
+ The required software you need is:
- The site consists of multiple modules: The Site itself and some
- helpers that must be installed in your local Maven repository. These
- extensions are currently not present in the remote Maven
- repositories, so if you do not install them, the site build itself
- will fail.
+ *) [Git](https://git-scm.com/) - to checkout and commit
+ *) [Docker](https://www.docker.com/) - builder.sh uses it to run Apache CMS that generates HTML out
+ of the Markdown files
+ *) A text editor - to edit the [Markdown](https://www.markdownguide.org/) files
+ *) A web browser - to review the changes in the generated HTML files
+ Steps:
-Checking the Site module out of the Velocity Source Code Repository
-===================================================================
+ 1) Create a parent folder for the local Git clones
- The site is available from
- http://svn.apache.org/repos/asf/velocity/site/ (The Apache Velocity
- Site repository). You need a Subversion client installed to download
- the site source code onto your computer.
+ export VELOCITY_PARENT_FOLDER="/path/to/velocity"
+ mkdir -p $VELOCITY_PARENT_FOLDER
+ cd $VELOCITY_PARENT_FOLDER
+
+ 2) Clone the GitHub repository for editing the Markdown files
+ git clone --single-branch --branch master git@github.com:[YOUR_GITHUB_ID]/velocity-site.git
+ 4) Edit the Markdown files
+
+ $VELOCITY_PARENT_FOLDER/velocity-site
+ edit src/content/[FILE].mdtext
-Create the Apache Velocity Site Helper modules
-----------------------------------------------
+ 5) Build the HTML files
- To build the site, you need the helper modules installed locally.
+ ./builder/bin/builder.sh
- The helper modules have been organized as a Maven reactor build. You
- can install them by running "mvn" from the "tools" sub-directory.
+ 6) Check the generated HTML locally
- You need to install these only once unless the dependencies of the
- site have changed which should only happen very rarely.
+ open $VELOCITY_PARENT_FOLDER/velocity-site-prod/index.html in your favorite web browser
+ and navigate around to review your changes
+ 7) Commit your changes
+
+ cd $VELOCITY_PARENT_FOLDER/velocity-site
+ git commit -a -m "Some message explaining your changes"
+ git push
-Create the Apache Velocity Site
--------------------------------
-
- To build the site, enter the "site" directory and run "mvn" (the
- default goal here is "site-post" which generates the site and also
- installs a few extra files (e.g. the download.cgi script for
- automatic mirror selection).
-
- If you want to re-create the site locally, you can now enter "mvn
- site:run" and point a web browser at "localhost:8080".
+ 8) Create a Pull Request in GitHub UI
Deploy the Apache Velocity Site
diff --git a/src/content/get-involved.mdtext b/src/content/get-involved.mdtext
index 51a1fd3..360b816 100644
--- a/src/content/get-involved.mdtext
+++ b/src/content/get-involved.mdtext
@@ -19,9 +19,9 @@
In this role, you participate in the actual development of the code. If this is the type of role you'd like to play, here are some steps (in addition to the ones above) to get you started:
+ [Read Guidelines](/how-it-works.html)
-+ Check Online Oocumentation
++ [Check Online Documentation](/engine/devel/getting-started.html)
+ [Download the Source Code](/download.cgi)
-+ Contribute Patches
++ Contribute Patches - the easiest way is to create a Pull Request (PR) at GitHub: [Engine](https://github.com/apache/velocity-engine/pulls) and [Tools](https://github.com/apache/velocity-tools/pulls). All PRs are automatically tested at TravisCI on both AMD64 and ARM64 CPU architectures.
Here is one developer's advice how to get involved. It specifically talks about Tomcat, but the general idea can applied to any of the projects.
