Github user swill commented on a diff in the pull request:
https://github.com/apache/cloudstack-www/pull/34#discussion_r99876892
--- Diff: README.md ---
@@ -15,14 +15,42 @@ Build the site with:
To serve it locally:
$ middleman server
-
-IMPORTANT: To publish your changes, commit the build into the asf-site *
branch *
-
-GOTCHA, *TODO*, the `build` directory needs to be renamed `content` in the
asf-site branch for the site to be served properly.
-
-*TODO* check the `build.sh` script and make it better, simple build that
stages all changes to `/content`
-
-Use GitHub PR to make changes.
-
-*TODO* Add gitHUB PR contribution instructions and better build
instructions for committers
-
+
+#Building
+To build the HTML files, you just need to execute the `build.sh`. The
script will automatically generate the HTML files and then move them to the
`content` folder.
+
+# Commiting
+Use GitHub PR to make changes. **No one should commit directly to Apache
remote repositories without opening a PR and waiting for proper review**.
+If you got the feedback and have amended the changes (if needed), it is
time to **commit** the changes to **Apache Software Foundation (AFS) remote
repository**. The ASF remote repository for this project is:
`https://git-wip-us.apache.org/repos/asf/cloudstack-www.git`
+
+**IMPORTANT:** To publish your changes, you should commit into the
**asf-site** branch (pay attention, this is the name of the branch in the
remote repository). **Do not forget**, you also have to commit the same changes
to the master; so, **master** and **asf-site** branches are synchronized.
+
+The **asf-site** branch is synchronized with a web server that delivers
the Apache CloudStack web pages.
+
+GOTCHA, the `build` directory needs to be renamed to `content` in the
asf-site branch for the site to be served properly; If you use the `build.sh`
script, this steep is already taken care of.
+
+## Step by step
+* Fork the repo to your own Github: `<your_github_user>`. To do that, you
can access `https://github.com/apache/cloudstack-www` and click on `fork` on
the right upper corner of the page.
+* Then, you can clone to you local git repo using: `git clone`; e.g. `git
clone https://github.com/apache/cloudstack-www.git` or `git clone
https://github.com/<your_github_user>/cloudstack-www.git`
+* `cd cloudstack-www`
+* __This step is only required for committers:__ (add the ASF remote repo)
`git remote add upstream
https://git-wip-us.apache.org/repos/asf/cloudstack-www.git`
+* if you have cloned directly from Apache namespace on Github, then you
need to add your namespace on Github as well, `git remote add
<your_github_user> https://github.com/<your_github_user>/cloudstack-www.git`
+* (get the master branch): `git checkout -b master origin/master` or `git
checkout -b master <your_github_user>/master`
+* Now, it is your turn to make the changes you want
+* `middleman build` will build/"compile" the HTML files from the sources
+* ` middleman server [-p <portnumber>]`. This will serve/deliver your HTML
files over HTTP. You just gotta access them using a browser; e.g.
`http://localhost:[port_configured]`. **Check your changes!!**
+* Execute `./build.sh`
+* `git add -A`
+* git commit -am "your commit message"
+* git push `<your_github_user>` master
+* Check if the changes appear properly on your Github project, and then
create a PR against the Apache `cloudstack-www` repo.
+* Get feedback on the PR and proceed once PR review is accepted
+* If you are not a committer, your job finishes here. Congratulations you
have made the Apache CloudStack website better :thumbsup:
+* Continuing, for committers. Clone or add the repo of our contributor on
Github using `git remote add <friend_contributor>
https://github.com/<friend_contributor>/cloudstack-www.git`
+* git checkout asf-site
--- End diff --
`git checkout asf-site` (added backticks)
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
