You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@jclouds.apache.org by Everett Toews <no...@github.com> on 2013/07/10 15:17:49 UTC
[jclouds-site] Make all refs relative to base tag. (#2)
https://issues.apache.org/jira/browse/JCLOUDS-169
You can merge this Pull Request by running:
git pull https://github.com/rackerlabs/jclouds-site relative-everything
Or you can view, comment on it, or merge it online at:
https://github.com/jclouds/jclouds-site/pull/2
-- Commit Summary --
* Make all refs relative to base tag.
-- File Changes --
M _config.yml (3)
M _includes/menu.md (8)
M _layouts/index.html (21)
M _layouts/jclouds.html (11)
M documentation/community/index.md (4)
M documentation/devguides/index.md (16)
M documentation/devguides/provider-metadata.markdown (2)
M documentation/examples/google-app-engine.md (2)
M documentation/examples/index.md (2)
M documentation/gettingstarted/index.md (10)
M documentation/gettingstarted/what-is-jclouds.md (6)
M documentation/index.md (16)
M documentation/jcloudsguides/index.md (14)
M documentation/quickstart/abiquo.md (4)
M documentation/quickstart/aws.markdown (2)
M documentation/quickstart/azure-storage.markdown (2)
M documentation/quickstart/bluelock.markdown (2)
M documentation/quickstart/chef.md (6)
M documentation/quickstart/cloudsigma.markdown (2)
M documentation/quickstart/filesystem.md (2)
M documentation/quickstart/hpcloud.markdown (2)
M documentation/quickstart/index.md (30)
M documentation/quickstart/openstack.markdown (18)
M documentation/quickstart/rackspace.markdown (22)
M documentation/quickstart/terremark-ecloud.markdown (2)
M documentation/quickstart/terremark-vcloud-express.markdown (2)
M documentation/reference/index.md (30)
M documentation/reference/jclouds-logging.markdown (2)
M documentation/reference/vmware-vsphere-design.markdown (4)
M documentation/releasenotes/1.1.0.md (6)
M documentation/releasenotes/1.2.md (68)
M documentation/releasenotes/1.3.md (86)
M documentation/releasenotes/1.4.md (78)
M documentation/releasenotes/1.5-tests.md (114)
M documentation/releasenotes/1.5.md (12)
M documentation/releasenotes/1.6-tests.md (134)
M documentation/releasenotes/1.6.1.md (2)
M documentation/releasenotes/1.6.md (2)
M documentation/releasenotes/beta7.markdown (6)
M documentation/releasenotes/index.md (46)
M documentation/userguide/blobstore-guide.md (4)
M documentation/userguide/compute.markdown (2)
M documentation/userguide/google-app-engine.md (2)
M documentation/userguide/index.md (42)
M documentation/userguide/installation-guide.md (20)
M documentation/userguide/terremark.md (4)
M documentation/userguide/using-ec2.md (6)
-- Patch Links --
https://github.com/jclouds/jclouds-site/pull/2.patch
https://github.com/jclouds/jclouds-site/pull/2.diff
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Everett Toews <no...@github.com>.
I have now tested this with Chrome, Firefox, Safari, and IE over both HTTP and HTTPS. You can see the HTTP version at http://166.78.23.198:4000/ (obviously that URL won't be valid forever).
In all 8 cases the site renders just fine. All of the links, images, styles, and fonts work. We have compatibility across all major browsers. It should be safe to try this out in production. We can always rollback quickly if necessary.
Including index.html for each link is not a show stopper. It's a simple way for us to make site validation simple for contributors. I doubt we'd have access to .htaccess on CloudBees. I trust @abayer to know what's possible in that regard.
@mattstep I understand that an experienced developer in many languages and sys admin like yourself wouldn't need this feature. I'll probably continue to use jekyll locally myself. However, that shouldn't prevent us from making it easier for anyone else to contribute documentation.
The barrier to doc contribution is too high right now. The real complexity is in getting jekyll installed. Juggling Ruby versions with rvm, having the right Python version, getting the correct gems install, and not screwing up any of your other dev envs along the way. Also keep in mind that all of these tools are non-Java based and quite possibly foreign to the majority of our user audience.
@abayer's experience getting jekyll running on Mac OS X is not an isolated incident. Heck, even getting jekyll installed on Ubuntu wasn't trivial and required updating, installing, troubleshooting, and Googling. I can't speak to what it's like to install on Windows but I'm sure it isn't any easier.
We can take all of the pain out of this process and have users contribute to documentation directly from their web browsers knowing that the site will render properly.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20845803
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Bayer <no...@github.com>.
+1 - doesn't break rendering, makes it easier to verify changes. What's not to like? =)
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20791706
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Bayer <no...@github.com>.
There has to be some way we can just post the output to a simple web server somewhere, with a link to that available from the PR build. Right? Or am I wishful-thinking?
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20849870
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Matt Stephenson <no...@github.com>.
As long as we stay on top of contributions it should just work then is what I'm hearing.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20886243
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Everett Toews <no...@github.com>.
Hold on a sec here. I thought of another approach last night that could work and we don't have to manage a web server. Here are the steps that the CloudBees build would take.
1. Site gets built by jekyll.
1. Site gets uploaded to Cloud Files container with a little bit of jclouds code.
1. Container gets CDN enabled on it so it can operate as a "[Static Website](http://docs.rackspace.com/files/api/v1/cf-devguide/content/Create_Static_Website-dle4000.html)".
1. URL to the static website is spit out in the CloudBees build (e.g. http://595ae8a4488249074e76-63df099925463e6a35e71531aa339bb1.r81.cf2.rackcdn.com)
Each build produces a unique container and URL. Because it has it's own subdomain we shouldn't need to fiddle around making everything relative. I.E. We shouldn't even need the changes in this PR.
Contributor and committer can review the site without worrying about it getting overwritten because it's unique. Containers will be removed periodically by a script that cleans out our Rackspace test account.
Thoughts on this approach before I head down this path?
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20887642
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Bayer <no...@github.com>.
That sounds pretty dang good to me.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20888209
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Bayer <no...@github.com>.
@mattstep - so the https change is because dev@cloud is on https://jclouds.ci.cloudbees.com - i.e., it's https, so the other non-https css/js includes broke. And the index.html appending is again 'cos of Jenkins - Jenkins' archived artifacts don't serve index.html if you go to .../job/foo/3/artifact/somedir/ - instead you get a Jenkins page listing the files in the dir.
If you've got ideas for a better way to get a visible site spat out from a pull request build, I know I'm all ears. =)
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20832626
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Matt Stephenson <no...@github.com>.
Thinking more on this, I really like the idea, it also helps with potential maximums on what we put into the site build, we could also stage the javadoc in this, with all versions and such, without blowing out the size limits in cloudbees.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20910482
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Phillips <no...@github.com>.
> But the CloudBees job builds against origin/master so
Actually, I think the CloudBees job builds against a "magic" repo that includes all the changes submitted as part of a pull request. Like the other pull request builders, it triggers as soon as the PR is (re-)opened.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20860545
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Phillips <no...@github.com>.
> There has to be some way we can just post the output to a simple web server somewhere, with a link to that
> available from the PR build.
>From what I recall, the only original objection to that was around credentials. Note that we already have a CI user for jclouds in order to publish the snapshots to the Apache repo - if those credentials can be given access to publish to a subdirectory of the jclouds site we could park the PR builds there and clean up every once in a while?
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20850320
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Ignasi Barrera <no...@github.com>.
Having the jclouds Jenkin plugin, if possible, would be perfect!
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-21075052
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Matt Stephenson <no...@github.com>.
Yeah, but we currently don't have the javadoc included, and it's been a pain to put somewhere in the past due to the size, if you take all the versions of it, i'm pretty sure it's going to cause similar issues as the snapshot repos.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20911737
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Bayer <no...@github.com>.
@everett-toews Yeah, I'm just tossing out ideas while doing 80 other things. =)
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20850808
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Bayer <no...@github.com>.
@demobox - I'm not sure if that'll work, though, since this isn't going to be Maven calls, I don't think. Encrypting the creds also won't work, at least in .m2/settings.xml style, 'cos that's just for Maven repo creds. Do we have a way to use encrypted creds with jclouds? If not, we should, like, do that. =)
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20995301
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Matt Stephenson <no...@github.com>.
@abayer read up on IE compatibility with link tags, as for index.html, i would try to find out how to make that work in jenkins, potentially with a .htaccess or similar.
This is a nice-to-have and should not compromise the site we publish, it's not worth it in my opinion to have jenkins generate a preview if it costs us IE users and having funky urls that might break if jekyll changes how the site is generated again.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20833197
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Matt Stephenson <no...@github.com>.
@everett-toews couldn't they just run the couldbees job that generates the site real quick? It's not like we have more than 5-6 concurrent PRs at a time on docs, and if we're moving stuff to the wiki, i don't see that increasing.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20852006
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Everett Toews <no...@github.com>.
@mattstep But the CloudBees job builds against origin/master so, as is my understanding, it only ever builds against the latest PR. How would they specify that they want to build their branch? Would closing and opening the PR be enough?
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20853881
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Everett Toews <no...@github.com>.
Closed #2.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Matt Stephenson <no...@github.com>.
There are unnecessary changes, it appends index.html all over the place which is ugly, and it may not work in all browsers for pulling in the css for the pages when it's run on an http server without ssl. How has this been tested outside of cloudbees?
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20793776
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Phillips <no...@github.com>.
> Thoughts on this approach before I head down this path?
All good, as long as we're OK having credentials for the upload in DEV@cloud
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20897404
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Everett Toews <no...@github.com>.
@mattstep I assume you mean your comment about beta7.markdown:L25. Yep. I just missed that one. Easily fixed.
I tested with IE 9. If you'd like to test against IE 7, do you have an instance of it that you can use to help us?
@abayer @demobox At this point we have a solution with CloudBees and wouldn't need to maintain any additional infrastructure, or store creds. Plus CloudBees will automatically only keep X builds. Yay less maintenance! Plus we still have the same relative URL problem with a simple web server somewhere and keeping multiple builds.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20850665
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Matt Stephenson <no...@github.com>.
Sounds great, as long as rax is willing to pay for it, would be good to use blobstore as much as possible in case we need to switch.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20895105
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Bayer <no...@github.com>.
https://wiki.jenkins-ci.org/display/JENKINS/Build+Secret+Plugin - we can upload a zip file with secret stuff in it. And fwiw, I can probably beg/borrow/plead with the Jenkins guys at CloudBees to get the jclouds Jenkins plugin onto our instance, even though it's not in the available list of plugins. That'd allow us to do blobstore publishing as part of the build using creds hidden off in Jenkins' config, etc...I'll ping people.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-21059238
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Matt Stephenson <no...@github.com>.
I guess to further state : this is a feature I personally won't use because I like the short feedback loop of running this locally. Again, lets make sure we don't make that development model more complex just for this.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20833321
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Everett Toews <no...@github.com>.
@demobox What's the best practice for storing creds in the CloudBees job? How do I use them afterwards? Feel free to just link me to any relevant doc (aka RTFM).
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20913438
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Gaul <no...@github.com>.
+1 making things easier for documentation contributors. Honestly I'm never going to bother figuring out whatever jekyll is. Pushing this into BuildHive strikes me as the correct approach despite any nits.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20846290
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Matt Stephenson <no...@github.com>.
@everett-toews It's simply ugly to append it, and the commit is inconsistent, in some cases you append index.html and in some you do not. If you did test it throughly I would expect this to error one way or the other.
I'm glad you tested it, the default settings in ie7 at one point did throw warnings though stating the page has mixed secure and nonsecure elements. I'm assuming you tested with this then, and it's simply that ms updated their browser to no longer throw this warning.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20846967
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Everett Toews <no...@github.com>.
@abayer Would that Build Secret Plugin be available in our CloudBees instance when the build starts running? How would that work?
I see what you mean about the jclouds Plugin from the "Publishing artifacts after a build" section but there might be a blocker. First off it needs to be able to upload the entire _site dir to a uniquely named container like _site_${BUILD_NUMBER}. The description on the plugin page makes it sound like it only uploads individual files.
The other blocker for the jclouds Plugin is a problem I ran into last night. You need to specify the Content-Type of objects in Cloud Files, otherwise browsers can misinterpret them. For example, the CSS won't get used properly because the Content-Type coming back from Cloud Files is application/unknown. There's a fix for this by setting the Content-Type for the objects individually as you upload them. I haven't had a chance to fully implement this fix yet though.
The jclouds Plugin could have other uses for us in the future so go ahead and pursue it if you like. I don't think we'll be able to use it for the site build though.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-21077204
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Bayer <no...@github.com>.
The build secret plugin is good for some stuff - I'm not entirely sure if that'll actually work here. Blergh.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-21082407
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Matt Stephenson <no...@github.com>.
@abayer @demobox I like this idea a bit better, it sounds easier to avoid breaking, i'm afraid we're going to end up with something that is different enough between cloudbees and the actual site that it's going to be easy to break one or the other. It feels counterintuitive for us to have to make this many changes just for a testing environment.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20851204
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Phillips <no...@github.com>.
> I'm not sure if that'll work, though, since this isn't going to be Maven call
Ah, then this won't work, indeed. Is there some "Jenkins secrets" plugin we could install for this? Certainly we can store anything in `/private` and get its contents with a `cat /private/something-or-other`, but that will not provide any _encryption_, obviously...
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-21039587
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Everett Toews <no...@github.com>.
@abayer @demobox @mattstep In addition to the credentials, another issue with using a simple web server somewhere is keeping multiple builds of the site around. To avoid the changes, we would have to deploy to root thus overwriting whatever else was there. That would make it difficult for committers to review a rendered change made by a non-committer. This is an important requirement.
That simple web server would also need to be maintained. Versus zero maintenance for CloudBees.
I agree that having to make changes to support a test env isn't ideal but sometimes it's necessary. Take the VisibleForTesting annotation in Guava for instance. The whole reason that exists is sometimes you need to make trade offs to enable testing.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20851873
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-site-pull-requests #8](https://jclouds.ci.cloudbees.com/job/jclouds-site-pull-requests/8/) SUCCESS
This pull request looks good
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20741209
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Bayer <no...@github.com>.
Well, posting to jclouds.incubator.apache.org isn't an option, since that's all in SVN etc.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20850660
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Phillips <no...@github.com>.
> The easiest way to store 'em would be to put them in ~/.m2/settings.xml
That's what we're doing right now, indeed. We encrypt them so at least they're not in plaintext. The key is also available so this is obfuscation rather than true encryption, but still.
You should be able to get hold of the file by accessing the `/private` jclouds repo (it's a WebDAV share) using your CloudBees credentials. Or let me know which credentials you'd like me to add and I can take care of that too...
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20994765
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Bayer <no...@github.com>.
fwiw, the size limits on CloudBees were entirely due to the legacy private Maven snapshots repo. Well, that and the legacy private release repo. Regardless, legacy Maven repos. =) And I'm in the process of nuking (after having backed up) the snapshots now.
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20911421
Re: [jclouds-site] Make all refs relative to base tag. (#2)
Posted by Andrew Bayer <no...@github.com>.
The easiest way to store 'em would be to put them in ~/.m2/settings.xml, which is copied from our private Forge to the slave. I'm not sure what other options there are along those lines, but there's gotta be something. =)
---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds-site/pull/2#issuecomment-20992996