add documentation for validate-downloads job

[mhdawson]

No description provided.

[mhdawson]

@nodejs/build any comments and if not can I get an approval so I can land.

[refack]

@mhdawson I added my nit fixes as a [suggestion] commit. Obviously feel free to push it out.

[gibfahn]

I'll review properly later today, but as an initial thought I'd rather we didn't start having separate documentation of these jobs, as in my experience it just gets out of date.

I'd rather we document the script clearly with comments, and then have the parameters just be the arguments to the script. If the way the parameter names map to the script is clear (it's either an environment variable, or it's passed in directly as an argument to the script) then that should be self-documenting. We could then have a single file that has an overview of each of the jobs to document what we have (i.e. the first paragraph of this doc).

I'll try to go through this in the next couple of hours and come up with something concrete.

[mhdawson]

@gibfahn waiting on your follow up input.

[gibfahn]

So I'd suggest having a single file jenkins/jobs.md with an entry for each job, and a link to the job. Then we document the job parameters in the job itself (otherwise we have to duplicate that info, people probably won't think to look here). I updated the job config to add some of the parameter info already.

jenkins/jobs.md:

# Jenkins Jobs ## [validate-downloads](https://ci.nodejs.org/view/All/job/validate-downloads/) This job validates that the downloads on nodejs.org are good. It is scheduled to be run nightly and can also be run manually after a release is made. **Note:** there is delay between when releases are generated and when they will be available on nodejs.org (up to 60 minutes) so releasers may have to wait a bit be able to complete the validation. If validation fails an email notification is sent to the `release-validation-alert` email alias. If you would like to get these notifications submit a PR to have your email added for that alias in https://github.com/nodejs/email/blob/master/iojs.org/aliases.json. This job needs to be updated each time a we roll over to a new Current release.

[refack]

@gibfahn can land?

[gibfahn]

Okay, pushed a commit to my branch that does what I suggested in earlier comments.

LGTM.

[mhdawson]

Landed as aed300d