Jenkins Documentation Office Hours, 6 Aug 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Jenkins Docs - Creating a redirect on jenkins io

Description

Video segment showing how a documentation developer can create a web page redirect on the www.jenkins.io site. Redirecting a page can help users by automatically taking them to the best page for their need.

A

So the problems the problems I encountered was, I thought I could just follow the pattern of redirects that were in the in the repository and then I attempted to make run and confirm that the redirects were working and couldn't test them. So the first question is: what's the format for a redirect and then the second question is: how do I test to be sure the redirect worked before I submit the pull request?

A

B

Do that I'll just share my screen: okay, okay!

B

B

Let's look how our redirects implemented actually yeah. If you go to the repository in content, easiest way to find redirects, uh there is just a redirect: folder, okay,.

A

All redirects are in that folder, no matter where they are in the structure of the repository.

B

Or no matter where.

A

They are no, they.

B

Are not okay, they are not. So that's the thing, because redirect is basically the same as everything else. It just has a special layout type, which is called redirect and when the website is generated, when this layout is passed, uh the page basically injects uh information, so either redirect or localized redirect, depending on your browser like so, basically, you get redirected to property url. If you navigate to link like.

A

B

Api token, so, let's see how it works, then say your redirect api token. Okay, no trailing.

A

B

Okay, now it doesn't work. So let's uh is because redirect so if we put redirect uh it should be working and it shouldn't really matter whether there is trading silence or not. Okay, all right. Okay, it matters if you configure redirects by vc host. So if you use always a way to define redirects here, then it really matters.

B

Okay, just my this host yeah. It's actually, I think you mean vhost.com. Oh we host right, uh yeah, we host conf and this one we need for confluence. Let's see yeah, you can see a bunch of redirects here. Yes, it doesn't matter whether you put slash or not same uh it matters for engine config.

B

If you have direct configuration engine config, which is the case for some locations within the website, but the modern way is to actually do it like that, and let me show a demo how to basically develop it locally.

B

A

B

Go back to jenkins io repository and yeah. We know that yesterday submitted a bug for redirect, which is here so redirect sex project to jenkins io. So, basically, what happened today at some point. We deleted the page uh but yeah due to the background implementation.

B

It doesn't mean that the page actually gets delivered delete from the production instance so because we just basically are sync files and we don't remove files which are not available. At least it's. My understanding of the bug.

A

Right, that's mine as well. The rsync doesn't do a minus minus delete or if it does something goes wrong. Yeah.

B

Okay, so in our case, what it means uh we have a link which is projects jenkins x. So here, let's sorry um so here we go to content and not the content, so projects and then projects. There is no jenkins x at all because at some point it was moved to a separate project and then basically.

B

We just deleted the entire content, just single play page from here, so we can actually see some examples so, for example, uh for ocean road map. We also use a redirect because at some point when the ocean project development was stalled, we put a redirect here.

B

So what I suggest to do do exactly the same for jenkins x, because we need to retain url structure and our only way is to actually put a link right inside uh still what you need to be keep in mind that, for example, this page projects listing is auto-generated, oh well. No, it's not actually auto-generated, it's just fancy syntax, so it should be. Okay, if you just add a additional project, there.

A

B

A

We do have some subdirectories, I think that have exactly the condition you're describing where they are auto generated, and I might have to do some exception in the auto generation. If I'm inserting a redirect.

B

Yeah or just type for type check for type of the page, so, for example, I do it uh in other locations.

B

So let uh let me yeah, I believe that adopters p, which is implemented like that for doctors, you can see that there is hummel. This hummel basically takes information from data adopters and yeah. Now there is no longer a type check, I believe, but yeah.

B

So here you can actually see the remainder of this check before we move to the data, so it just checks whether the page is readme. You can also check for the type of patient, for example, ignore redirects.

A

Okay, so so, for instance, here the fact that I removed t-mobile as an adapter, it was it was handled very nicely because there isn't a t-mobile page. That's created the the adopters page is generated from data. That's the assembly of a series of adoc files.

B

All right and at the same time there is no so these data pages they're not mapped to the website, so they're not published as pages got it right for you, it was enough. Otherwise you could have hit the same bug.

B

So what we will do here, let's go back to our redirects, so we have our products I'll take redirect from blue ocean, and I just put it on the top level here and here's the name jenkins x.

A

Right so you're not creating a new folder named jenkins x and an index.a doc inside it you're just creating jenkins x.a doc.

B

Well, it doesn't matter, you can do it either way: okay, all right uh yeah, and uh in this uh task we were asked to actually redirect to this jenkins page. So this is exactly what we will do. We will put a redirect url here. Obviously they don't have relativization, urls, etc and yeah. We can just keep it as this, so in redirects you basically have two ways. One way is to put absolute link. Another way is to actually put a relative link, though I'm not 100 sure whether we actually use it anyway.

B

These days uh but yeah related redirect links should also work.

A

ah Okay, so so, if if it had been a redirect to another page inside and and can I embed um ids inside the redirect url, so xyz hash mark one two three uh so so, could I put a redirect, could I put a hash mark inside the redirect url?

A

um Oh I I may have to quote it: okay,.

B

Yeah, you can quote and put everything in basically any content, but this yaml doesn't support variable resolution, so it should be absolute value without any additional macros or whatever.

B

Okay, okay and yeah, I'm just a chicken, so relative urls should be also see used for sex and study yeah. When you replace the core sex installer yeah, I used relative redirects and they were okay, great okay. So here what we added? We added the jenkins text page and projects which points somewhere. Now I will just launch the.

B

Site so it may take a while, uh but there should be no magic. It should work.

B

uh What you need to keep in mind that since we modify metadata, uh the change won't be reliably applied until you reload the same time after recent updates of our struct. It actually sometimes works. So if you want, we will verify it once it loads. So I'm not sure I understand what you mean by by reload. What what do you mean there? Is that uh when you develop, uh let's say common content, like pages like that, you can just write text, it'll load the page in your browser, and you will see your content.

B

uh It will not be a case for this page, if I recall correctly, but yeah, let's try it. Okay, yeah.

A

All right, so so what you said triggered matches for me with the experience that sometimes I have to stop and do make run again. I think that's, that's! Okay! Got it.

B

Yeah, this experience actually greatly improves because we also update dependencies. So, for example, now images will get updated if they change, but they still need to be indexed. So, if you add new images same as, if you need new pages, you have to restart otherwise these pages will not be discovered the same, for example, for data files. So if you modify anything there like that or unfortunately change log, then you need to see the effective result.

A

Okay, now now I've had while we're waiting for that to generate, and as soon as it's done, we can certainly go back to it, but I've had one more time. Okay, I've had one more challenge with generation that I'm not quite sure how to resolve, and that's with the change log. The new downloads page includes a computation that uses the sha-256 hash in the page and if I reference a bill that does not yet exist.

A

As far as I can tell page generation fails, um is there a way for me to conditional that so that it doesn't so that, instead of failing it will just leave the sha 256 blank or some.

B

A

In the downloads right, yes yeah, so I usually navigate to the changelog page by going through downloads, and if I'm referencing a build that does not yet exist. The downloads page doesn't work because I think because it can't find the shot 256 for that that build or it's trying to get some other data about the build. Have you reported.

B

A

No, I have not, because I've been busy, no, not at all. I have not reported it.

B

Okay, so here you can see the code while we wait, so you can see that it actually goes uh to jenkins maven repository and reads the entire sh file so yeah it will fail if open operation fails.

B

So here the tricky thing is to actually understand what happens, because so this part is basically uh part of ruby code inserted into the jelly file in the hammer file. Sorry, so it's not enough!

B

So if they don't have a conditional, open operation or whatever, then you don't have much option here, because it's basically this operation which fails so it fails to download the data and likely it throws exception.

A

Got it okay, so so that's the place. I need to investigate and I certainly can investigate to see if I can find a conditional operation in ruby or okay great so.

B

You want a solution which is guaranteed to work. You can replace this code by ruby. You can put it somewhere, just a second, uh for example, uh when we do that.

B

In this repository.

A

So there's a way, there's a way to actually put ruby functions or ruby, ruby methods.

B

Oh nice, okay, not not these ones, just a second I'm trying to remember where you put it but yeah. You can put some ruby coat right inside the repository and it could be the conditional open, then yeah, so just a second, and also you can put it in other components. For example, this is how we pre-vision macros macros are written in ruby, but yeah again you shouldn't really need it.

B

Second yeah! I forgot where it's located so yeah, that's so.

A

B

Way to get it is like that, so here you can see that, for example, uh there is already some content text which puts great guide and it does some magic in ruby. So basically you can just to track edge and whatever other stuff needed there and hence prevent the error.

B

A

Okay, so so those all right is it excellent. Thank you thanks very much.

B

Okay, so while we were talking, uh our site has started for me yeah. This recording takes extremely long time on this laptop.

B

Okay, so here's our site, here's our sub projects and sub projects. We don't see drinking sex, which is good at the same time. Let's go to the projects just to make sure we.

B

Okay, there is jenkins x here but I'll. Let me guess that there's a jenkins sex here, because nobody really deleted them from or from here.

A

Yeah, interesting, okay, so so that that may be another one we need to get rid of, but but okay.

B

So yeah you can uh take it as a home task right but yeah whatever. So uh what we need to uh check so here it's uh replaced uh to redirect.

B

uh So it's not redirect it's just hardcoded in the definition. We can check it if you want, but it's definitely hard coded. uh Okay. I shouldn't have been opening so many tabs, so projects uh jenkins yeah it's in index. So here you can just scroll to jenkins x and you can see this content there.

A

B

Is right: okay, okay, now, let's uh try our redirect projects uh jenkins x.

B

Yeah so now redirect works.

A

Victory: okay,.

B

So if you put a custom link, you get no not found, but it's fine, because this page had no sub pages. If you take something like that, it works actually. Okay, not exactly like that. Sorry um yeah, so jenkins, x, yeah, custom page.

B

It won't redirect you, but if it's an occurring link it will redirect you if I recall correctly, yeah, okay, okay, so we can also test whether life reload works here now, but yeah, I'm not.

B

A

Oh good, okay, so it it. Even though that was that's a data thing, it somehow re-read the data.

B

Yeah so again we keep updating our upstream dependencies. We use abstract, which is framework not maintained by us so yeah. At some point they improved the behavior for.

B

A

And oleg, you don't need to actually do this. I can take it from here if you'd like it's a great experience for me to redo and be sure that I know how to do it.

B

Well, you will have an opportunity to do that because uh I'm doing 241 one link and you still have that's true- I've got to do the t-mobile and yeah good, okay, yeah I'll, just put it since I have it anyway,.

B

So, do we just remove it from projects.

A

I think we should I I don't see any reason to have have it listed there in projects. I think we should also remove evergreen from projects. Okay,.

B

Well, evergreen yeah. We have an action item to actually park it. It's uh it's a bit more than that and yeah for evergreen. It's already a bit strange because it's listed as subproject. It's not listed here right because we dropped it at some point. Okay, so we then remove jenkins x and 30, and we also need to update the row here to large.

B

So we need to relent the image for gcask.

B

A

Because the images are intentionally alternating got it well.

B

At some point this looks cool. It does look good. I like that. Okay, it's not our the most active page.

B

Okay, okay, so we need this fix. I push it to my remote yeah. So basically do you know what happens next.

A

So so vs code does not have an interface to the hub command.

A

You might you, might you might explore that because I love the hub command because it will. Let me do this from the inside my ide as well. Well, uh most likely.

B

It has I'm not actively using that. ah Okay yeah. I believe that it's something okay, hubcrap um yeah, so that is yeah like yeah. It looks like there are several good okay. Well, uh basically, this console is yeah. You cannot hop to just your pass if you want, so it depends on what is your preferences right in my case, yeah.

B

So what was the default number.

B

Okay: okay, let's quit the bug, it doesn't really matter.

B

A

Here's our request, excellent and github did the connection between that did the linking because you referenced it in the the text it linked it in the bottom right. Excellent, very good! Okay, thank you! So yeah! Basically, that's it!

A

Thank you. Oleg thanks very much.