documents the custom assets page

[anarcat]

It would seem like a good idea to document how the custom assets system works somewhere.

In two distinct issues, #74 and #73, I needed access to the repo and couldn't self-discover it. a roundtrip would have been avoided if this was documented better. furthermore, I could make changes because i'm in the srv-manpages group, so it would be nice to also document how we can join that group.

where should we do this? in about.html? an eventual FAQ? re #61?

so here's a wishlist of things to document:

• how to checkout the source of the custom assets (in about.html? faq.html?)
• when and how are assets re-injected in the main website (automatically? frequency?)
• how to get write access to the repository (rt.debian.org?)

thanks!

[anarcat]

in the faq branch of the static assets repo, I have added a faq.html page which covers two of the above issues. please review if the answer is accurate.

then we just need to document how often changes kick in and how they are deployed.

thanks!

[stapelberg]

In general, the FAQ looks good.

Note: the Github issue tracker is for software-specific issues. If there are issues with the service (e.g. server not found or other service issues), the bug should be reported against the manpages.debian.org pseudo-package. (Currently unavailable, see bug #851885.)

Not sure if we want to make that distinction. Personally, I’d prefer everything to go into the GitHub issue tracker.

Pushing to that repository requires access to the srv-manpages group, which is granted through a request on rt.debian.org.

Actually, you’ll need to apply to become a member of https://alioth.debian.org/projects/srv-manpages/, which has nothing to do with RT :).

then we just need to document how often changes kick in and how they are deployed.

Debiman is run after the archive update was pushed to the local mirror at bytemark, i.e. 4 times a day. After processing time (on the order of minutes), there’s an additional delay for pushing the resulting content to the static mirroring infrastructure. Notably, changes to the templates are only picked up when a manpage is re-rendered anyways, so we’ll need to force a full rerender, which takes on the order of hours.

[anarcat]

Not sure if we want to make that distinction. Personally, I’d prefer everything to go into the GitHub issue tracker.

Okay then - maybe just mention the BTS for people that don't or can't use github?

Actually, you’ll need to apply to become a member of https://alioth.debian.org/projects/srv-manpages/, which has nothing to do with RT :).

Understood, fixed.

Debiman is run after the archive update was pushed to the local mirror at bytemark, i.e. 4 times a day. After processing time (on the order of minutes), there’s an additional delay for pushing the resulting content to the static mirroring infrastructure.

Alright, added that to the FAQ.

Notably, changes to the templates are only picked up when a manpage is re-rendered anyways, so we’ll need to force a full rerender, which takes on the order of hours.

Okay - should I know how to do this myself? :)

[stapelberg]

Okay then - maybe just mention the BTS for people that don't or can't use github?

Yep.

Notably, changes to the templates are only picked up when a manpage is re-rendered anyways, so we’ll need to force a full rerender, which takes on the order of hours.

Okay - should I know how to do this myself? :)

IIRC, I never mentioned how this works :). This is the command I used last time, note the -force_rerender flag:

manziarly % sudo -u manpages \
  /srv/manpages.debian.org/debiman/run-debiman.bash \
  -force_rerender 2>&1 | tee ~/dm-full-rerender.log

I recommend logging the output to file (as the command does) so that we have it in case things go wrong.

You’re welcome to merge the FAQ branch into master and trigger a full re-render. Let me know if you’d prefer me to do this.

And thank you very much for your work on the FAQ, it’s much appreciated. I reviewed the commits and they look good to me.

[anarcat]

i have tried to run the given command, but it seems i lack the sudo privileges, even though I am in the right alioth group.

$ sudo -u manpages   /srv/manpages.debian.org/debiman/run-debiman.bash   -force_rerender 2>&1 | tee ~/dm-full-rerender.log

We trust you have received the usual lecture from the local System
Administrator. It usually boils down to these three things:

    #1) Respect the privacy of others.
    #2) Think before you type.
    #3) With great power comes great responsibility.

[sudo] password for anarcat on manziarly: 
^C
anarcat@manziarly:~$ id
uid=3160(anarcat) gid=3160(anarcat) groupes=3160(anarcat),800(Debian),1240(apachectrl),3407(manpages)

am i doing something wrong? i'm not used to sudo usage on DSA machines... maybe I'm missing something?

should this procedure be documented in the FAQ as well? if not there, then where?

[stapelberg]

Did you set a sudo password in db.debian.org as per https://dsa.debian.org/user/sudo/?

If that doesn’t fix it (after the 30m propagation delay), please contact DSA directly.

If it helped, feel free to add the pointer about sudo to the FAQ, though I expect it to be of limited value, given the small set of humans who’ll be able to benefit from it :).

[anarcat]

ah, right, finally figured out that one. :) i'll document this in the FAQ before closing here. the job is running now...

[anarcat]

the full render is still running, unfortunately not in a screen session so it's possible it gets interrupted. hopefully it will be done within the next few hours and all pages will show a link to the FAQ.

i've also added the magic incantation to the FAQ, hopefully it makes sense.