THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Anyone can make changes to the public website, but only authorized people can merge the changes, just as you would expect. This document is for anyone, except the last few instructions about merging PR's.
Apache Rya Web site source
The project git@github.com:apache/rya-site.git (https://github.com/apache/rya-site) is the markdown source code of the official Apache Rya website.
- master branch is the source in markdown for the Jekyll tool.
- asf-site branch is the compiled HTML that is deployed to the webserver.
The master branch is processed by Jekyll and committed to the asf-site branch. The latest commit to asf-site is automatically served as http://rya.apache.org/
Modification
To make changes to the website:
1. Clone rya-site branch master:
git clone https://github.com/apache/rya-site.git
cd rya-site/
2. Create a new branch: git checkout -b your_new_branch_name_here
3. Modify the markdown as needed using a text editor.
4. New releases go in folder _posts along with other news.
5. Releases must use the prescribed file naming format and have a header variable catagories=release along with some other variables describing the version.
6. The file download.md, using its scripts, should automatically populate the corresponding html based on your new post file and its variables, but it may need tweaking.
7. Install Jekyll. This may not be straight forward if you don't have a ruby environment. You may have to add Linux distro packages, then ruby gems, then more packages as dependencies present themselves. Some instructions are at https://jekyllrb.com/docs/installation/ Make sure you update the version of jekyll used by bundle (bundle update)
8. Run this command in the content/ folder to auto-compile and web serve on port 4000: cd content/ bundle exec jekyll serve
On a VM: Set up a port forward in VirtualBox's network settings for port 4000. Use the host option with 0.0.0.0 to publish to the host.
bundle exec jekyll serve --host 0.0.0.0
Alternatively, you can use docker to build and serve the site:
export JEKYLL_VERSION=3.8
docker run --name rya-site --volume="$PWD:/srv/jekyll" --volume="$PWD/vendor/bundle:/usr/local/bundle" -p 3000:4000 -it jekyll/jekyll:$JEKYLL_VERSION jekyll build
docker run --name rya-site --volume="$PWD:/srv/jekyll" --volume="$PWD/vendor/bundle:/usr/local/bundle" -p 3000:4000 -it jekyll/jekyll:$JEKYLL_VERSION jekyll serve
open a browser to http://localhost:3000/
9. Now just iteratively use your editor and web browser to edit and test changes.
When you are done making changes:
11. Move the content/target folder out of the way, you will commit this separately.
mv content/target/ ../
12. Commit changes, add a remote to your own public git repo, and push to it with --set-upstream.
12.1 commit changes
git add [new and modified files]
git commit -a -m "say what you changed here"
12.2 add a remote to your own public git repo, for example
git remote add your_username https://github.com/your_username/rya-site.git
12.3 push
git push your_username your_branch_name_here --set-upstream
13. Create a pull request to the repo apache/rya-site branch master.
Here is a guide https://help.github.com/articles/creating-a-pull-request-from-a-fork/
Now for the deployable HTML that you moved above:
15. In the same git folder, git checkout --force origin/asf-site git checkout -b another_new_branch_name_here rm -r contentNote: --force might remove any stray files left over.
Note: replace another_new_branch_name_here with a new branch hinting at your changes.
Note: the recursive remove of all the content is necessary to discover files deleted as well as changed.
16. Now copy the folder formally named target/ into the project, renaming it to content/.
mv ../target/ ./content
17. Use git status to observe changes. The css and other template files are probably not changed. If they are flagged as modified, investigate CRLF or other trival differences. See .gitattributes. Try git diff *css. The file permissions might be different: chmod -R 755 *
18. When done, commit to your repo in a new branch as above.
19. Create a pull request as above, except to be merged into branch asf-site.
20. Beg and bribe peers and mentors to review changes. Consider hosting the site temporarily for review, see below.
21. Make changes and commit them as above. No need to create new pull requests as they follow the latest commit in the branch.
Hosting for review on Github pages
1. Review the setup here: https://pages.github.com/ using "project-site"
2. It doesn't mention it in the quick start above, but it will also publish a site from a branch named "gh-pages" which is important since master is already used for another purpose.
3. Start with your branch of project "rya-site" as pushed to your remote, that is based on the asf-site branch.
4. Create and checkout a new branch named "gh-pages". This will not be used in a pull request.
git checkout -b gh-pages
5. Move the contents of the "content" folder to the root of the project.
6. Modify each HTML page prepending to all references (href= and src=) to the site with "/rya-site" . Ignore references beginning with http.
For example:
Before:
<link href="/assets/themes/apache/bootstrap/css/bootstrap.css" rel="stylesheet">
After:
<link href="/rya-site/assets/themes/apache/bootstrap/css/bootstrap.css" rel="stylesheet">
This command should do the replacement: find . -name \*.html -exec sed -ri 's/=\"\//=\"\/rya-site\//g' {} \;
7. Commit changes and push to your public github project named rya-site. git commit -a -m "New stuff" git push git push --set-upstream yourGitHub gh-pages
8. Login to your github account and to the project rya-site forked from apache/rya-site, and click on the Settings tab. Scroll down to GitHub Pages and choose source=gh-pages branch. Save.
9. Browse to the site:
https://yourGitHubID.github.io/rya-site
replacing yourGitHubID with your GitHub account ID.
10. Check your work and ask others to review by sending this URL.
Review and Merge
1 Create a pull request for merging into master, and a separate one for asf-site.
2 After reviews are complete, an authorized person can pull master and pull asf-site in the usual way.
Important note to the person pulling the new changes: Be sure that the asf-site matches content in master. It might be safer to ignore the asf-site pull request and compile the modifications from master.