Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

actions: build manuals #88488

Closed
wants to merge 1 commit into from
Closed

actions: build manuals #88488

wants to merge 1 commit into from

Conversation

@zowoq
Copy link
Contributor

zowoq commented May 21, 2020

Continued from #87853

cc @grahamc @Mic92

Using ofborg is probably better but this might be useful for now?

This action will only start if something in /doc or /nixos/doc is modified so most contributors shouldn't see it.

Each job will skip the cachix action/building the manual unless its paths have changed.

They could be split further into one action per path if we really wanted to save a couple of seconds.

@zowoq zowoq force-pushed the zowoq:manual branch from e8b279f to 1acbf04 May 21, 2020
pull_request:
branches:
- master
paths:

This comment has been minimized.

Copy link
@Mic92

Mic92 May 21, 2020

Contributor

Should we also include nixos/modules/**? I had a few cases where module option description broke the manual. Of all PRs we have only a few are touching modules.

if: steps.git_diff.outputs.diff
- name: build nixpkgs manual
if: steps.git_diff.outputs.diff
run: nix-shell doc/shell.nix --run 'make -C doc'

This comment has been minimized.

Copy link
@Mic92

Mic92 May 21, 2020

Contributor

According to the manual https://nixos.org/nixpkgs/manual/#chap-contributing we build it with nix-build ./doc. However it also says that make -C doc debug might come in handy in case there are errors.

This comment has been minimized.

Copy link
@Mic92

This comment has been minimized.

Copy link
@zowoq

zowoq May 22, 2020

Author Contributor

I hadn't noticed that ofborg is running instantiate for the manuals, nixpkgs has pkgs/top-level/release.nix -A manual.

@zowoq
Copy link
Contributor Author

zowoq commented May 22, 2020

The outcome of the doc format RFC could mean that this isn't needed in a few months which might actually be a point in its favour as it can be easily dropped.

I'm assuming that adding these builds to ofborg is non-trivial and wouldn't be a productive use of time if we might end up changing formats anyway.

@Mic92
Copy link
Contributor

Mic92 commented May 22, 2020

I also like github workflows for these sort of task more since they don't involve writing Rust and are easier to prototype.

@grahamc
Copy link
Member

grahamc commented May 22, 2020

@grahamc
Copy link
Member

grahamc commented May 22, 2020

cross-posted from #87853:

I would like to revert this PR and close #88488. Not because I don't like github actions or feel like my pet project ofborg is threatened, but because I think these checks are actually harming the clearness of the checks. I'll explain:

The editorconfig check puts a big green check next to a commit, and hides the list of checks which passed. If ofborg is down or behind, it is likely people will think ofborg has approved the PR before it did. This could cause, well, all the problems ofborg is there to prevent.

The concrete problem here is this green check appears very early and is misleading, and there is no poka yoke to help people do the right thing.

One fear of #88488 is that it will introduce red X's if it takes a long time to build the manual, or something in the target branch is failing to build. This is reminiscent of the Travis times for me: Travis gave out so few green checkmarks, that if Travis gave a PR a green check-mark, it inspired more "okay what is broken that let travis pass it?" than "okay good to merge".

The goal of ofborg, and ever since ofborg became a thing, the "rule" has been green checkmark -> good to merge and red X -> don't merge.

The editorconfig check errodes the clearness of the green checkmark signal.

The big-rebuild failures we'll certainly have with #88488 errodes the clearness of the red X signal.

The clearness of this signal has been my guiding light on the design of ofborg for years now, and I am very afraid of threatening it.

A few suggestions that have been brought up to improve this:

  1. make ofborg faster I'd love to do this, but it doesn't solve this problem if ofborg is seriously delayed or down.
  2. require the ofborg evaluation check for merges this is really the only solution, but not something we can do today, because of some workflow issues we need to resolve.

That makes me think that, today, we should be undoing this check and closing #88488.

@zowoq zowoq closed this May 22, 2020
@zowoq zowoq deleted the zowoq:manual branch May 22, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

3 participants
You can’t perform that action at this time.