A CI.md is required

[mawaregetsuka]

What is the problem this feature will solve?

Let people know more about CI in node

What is the feature you are proposing to solve the problem?

Describe the main steps of CI in node and some important details.
Relationship between CI and PR.
Common problems and recommended solutions when PR enters ci phase.

What alternatives have you considered?

No response

[Trott]

The information is in https://github.com/nodejs/node/blob/master/doc/contributing/pull-requests.md#continuous-integration-testing. Anything missing can be added there.

[mawaregetsuka]

Yeah. but in my case I'd want to konw more details about it like "What exactly is each CI job doing?" and "What do we do if some jobs end up in Failed or Unstable state?".

[Trott]

Yeah. but in my case I'd want to konw more details about it like "What exactly is each CI job doing?"

What's an example of a CI job that is unclear in that regar?

and "What do we do if some jobs end up in Failed or Unstable state?".

That can definitely go in that doc. (The answer is: Look and see if it's related to your changes. If it is not, you can choose to do nothing or you can ask someone to re-run CI.)

[mawaregetsuka]

What's an example of a CI job that is unclear in that regar?

I've noticed that Jenkins's job set isn't always the same, there are dozens of jobs that can appear in the set.

That can definitely go in that doc. (The answer is: Look and see if it's related to your changes. If it is not, you can choose to do nothing or you can ask someone to re-run CI.)

How can the problem be resolved if it is only on a particular platform?

[mawaregetsuka]

Maybe my description is not very clear, I am adding
1 ci uses GitHub Actions and Jenkins I'm not sure if there are other, what does a complete ci pipeline look like and where to see it?
2 The same ci job sometimes succeeds sometimes fails, what are the limitations of the current ci process and the current direction of improvement.
3 I think it is very difficult to locate the cause of failure in ci, at the moment is there a recommended way?

If some of the above is invisible to non-collaborators maybe we should add additional clarification to the documentation?

@Trott

[Trott]

I agree this stuff should be documented. I'm not sure CI.md is the place for it but there also aren't a lot of other high-visibility options.

[sxa]

1 ci uses GitHub Actions and Jenkins I'm not sure if there are other, what does a complete ci pipeline look like and where to see it?

Is this specifically related to the pipelines for testing PRs (mostly https://ci.nodejs.org/job/node-test-pull-request/) or are you askign about how other jobs in the jenkins instance work?

3 I think it is very difficult to locate the cause of failure in ci, at the moment is there a recommended way?

At a high level I tend to "follow the red" from the node-test-pull request job and then look at the console log for the lowest level 'red' job. It would be great if you had a specific example (or examples!) we could look at that you've struggled with. That way we could work to understand what documentation could be put in place that would help.

And to @Trott

If some of the above is invisible to non-collaborators maybe we should add additional clarification to the documentation?

👍🏻 - I also agree that unless there's a huge amount of information that we want to put in there, adding to the additional docs rather than creating a new md file is the bet approach here - butas you say it needs to be discoverable if we put it in place.

[mawaregetsuka]

Is this specifically related to the pipelines for testing PRs (mostly https://ci.nodejs.org/job/node-test-pull-request/) or are you askign about how other jobs in the jenkins instance work?

I think it's all but PR related has a higher priority.

At a high level I tend to "follow the red" from the node-test-pull request job and then look at the console log for the lowest level 'red' job. It would be great if you had a specific example (or examples!) we could look at that you've struggled with. That way we could work to understand what documentation could be put in place that would help.

I think the difficulty lies in the lack of understanding of CI process and the same job that sometimes works and sometimes doesn't(Based on my observations, I think this frequency is high). #41565 perhaps the CI process in this PR is a good example.

And about CI.md it's just one way. it would be nice if there were a better place for these things.

[sxa]

I think the difficulty lies in the lack of understanding of CI process and the same job that sometimes works and sometimes doesn't(Based on my observations, I think this frequency is high).

I suspect many of them are either unknown or will get fixed as soon as they're discovered and understood (Such as 41565 that you referenced, although that took a while to get merged) so putting together anything more detailed on specific cases would be quite tricky.