geode-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kmil...@apache.org
Subject [1/2] incubator-geode git commit: GEODE-1759: Improve geode-site/website/README.md
Date Fri, 12 Aug 2016 17:57:17 GMT
Repository: incubator-geode
Updated Branches:
  refs/heads/develop f0eb44eec -> a75c59a33


GEODE-1759: Improve geode-site/website/README.md

Clarify what needs to happen on which branch and in which
directory to update the Apache Geode website.


Project: http://git-wip-us.apache.org/repos/asf/incubator-geode/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-geode/commit/e66f58ac
Tree: http://git-wip-us.apache.org/repos/asf/incubator-geode/tree/e66f58ac
Diff: http://git-wip-us.apache.org/repos/asf/incubator-geode/diff/e66f58ac

Branch: refs/heads/develop
Commit: e66f58accad7b069607349d2be1755446d8577a9
Parents: 5fac815
Author: Karen Miller <kmiller@pivotal.io>
Authored: Fri Aug 12 10:51:05 2016 -0700
Committer: Karen Miller <kmiller@pivotal.io>
Committed: Fri Aug 12 10:51:05 2016 -0700

----------------------------------------------------------------------
 geode-site/website/README.md | 69 ++++++++++++++++++++++++++++++---------
 1 file changed, 53 insertions(+), 16 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/e66f58ac/geode-site/website/README.md
----------------------------------------------------------------------
diff --git a/geode-site/website/README.md b/geode-site/website/README.md
index 60deb69..474e6ca 100644
--- a/geode-site/website/README.md
+++ b/geode-site/website/README.md
@@ -6,9 +6,13 @@ Source files for the website are in ``${geode-project-dir}/geode-site/website/co
 
 Generated files for the website are in ``${geode-project-dir}/geode-site/content``
 
-The website is updated by a "sync" tool that monitors the __asf-site__ branch of our Git
repo, so after making changes you must push your updated source and generated files to that
branch. The content will be published to the [Geode website](http://geode.incubator.apache.org),
after a 5-20 minute delay.
+The website is updated by a "sync" tool that monitors the __asf-site__ branch 
+of our Git repo, so after making changes you must place your updated source
+and generated files on the __asf-site__ branch and push.
+The content will be published to the
+[Geode website](http://geode.incubator.apache.org) after a 5-20 minute delay.
 
-## Prerequsites
+## Prerequisites
 
 To generate the site locally, you need Ruby, Python, Pandoc and a couple of Ruby Gems.
 
@@ -29,30 +33,63 @@ Install Nanoc and other Ruby Gems needed:
 
 ### 1. Find and edit the source files you need to change
 
-Generally, you should make your changes in the __master__ branch unless you have a very good
reason to do otherwise. When you're ready to publish, merge them to the __asf-site__ branch.
+Source files for the website are in
+``${geode-project-dir}/geode-site/website/content``.
+When changing the actual content of the site, find the Markdown files that you
+need to edit under the ``${geode-project-dir}/geode-site/website/content/docs``
+directory and make your change.
 
-If you are changing the actual content of the site, then find Markdown file that you need
to edit under the ``content/docs`` directory and make your change.
+If you need to change the layout or styling of the site,
+then you will probably need to change an HTML, JS or CSS file 
+within the ``${geode-project-dir}/geode-site/website/content`` directory.
 
-If you need to change the layout or styling of the site, then you will probably need to change
an HTML, JS or CSS file under the ``content`` directory.
+### 2. Locally generate the site and test your changes
 
-### 2. Generate the site
-
-Run the nanoc compiler to generate the site. It is configured via the ``nanoc.yaml`` to place
website files into the ``content`` directory at the top
+Run the nanoc compiler to generate the site.
+Nanoc is configured by the
+``${geode-project-dir}/geode-site/website/nanoc.yaml``
+file to place the locally built website into the
+``${geode-project-dir}/geode-site/content`` directory.
+With a cwd of ``${geode-project-dir}/geode-site/website``:
 
     $ nanoc compile
 
-Run ``git status`` and you should see your changes plus some update files under the ``${geode-project-dir}/content``
directory.
-
-### 3. Test your changes locally
+Run ``git status`` and you should see your changes plus any updated files
+under the ``${geode-project-dir}/content`` directory.
 
-To test locally, use the view command to start a local web server. Check the website at [http://0.0.0.0:3000](http://0.0.0.0:3000)
+To view your changes locally, use the view command to start a local web server. Check the
website at [http://0.0.0.0:3000](http://0.0.0.0:3000)
 
     $ nanoc view
 
-To make changes, stop the web server, edit files, recompile, and view again.
+To make further changes, stop the web server, edit files, recompile, and view again.
+
+### 3. Publish your changes to the site    
+
+Once you are happy with your changes, commit them to the __develop__ branch.
+The changes also need to be propagated to the __asf-site__ branch.
+However, the file structure of the __asf-site__ branch is unusual, so a
+git merge will not do the right thing.
+
+The compiled ``${geode-project-dir}/geode-site/content`` directory 
+from the __develop__ branch will need to be placed at the 
+top level, ``${geode-project-dir}``, of the __asf-site__ branch.
+Here is one way to accomplish this:
+
+1. On the __develop__ branch
+    
+        $ cd geode-site-website
+        $ nanoc compile
+        $ cd ../content
+        $ tar cvf new-website-content.tar .
+        $ mv new-website-content.tar ~/Desktop/.
+The move of the TAR file is not necessary, but helps to clarify this example.
+
+2. Expand the TAR file at the top level of the __asf-site__ branch
 
-### 4. Publish your changes to the site    
+        $ cd ..                  (cwd should be ${geode-project-dir})
+        $ checkout asf-site
+        $ tar xvf ~/Desktop/new-website-content.tar
 
-Once you are happy with your changes, commit them, merge to the __asf-site__ branch and push.
+3. Commit and push on the __asf-site__ branch
 
-The site should update in 5-10 minutes and if not [file a JIRA against the INFRA project](https://issues.apache.org/jira/browse/INFRA)
or ask for advice on the Infrastructure project's HipChat room [#asfinfra](https://www.hipchat.com/g4P84gemn).
+The site should update in 5-10 minutes. If it does not, [file a JIRA against the INFRA project](https://issues.apache.org/jira/browse/INFRA)
or ask for advice on the Infrastructure project's HipChat room [#asfinfra](https://www.hipchat.com/g4P84gemn).


Mime
View raw message