Use of randomness in build

[TysonMN]

I think the build uses randomness to generate IDs. For example, this commit in my gh-pages branch contains a change from the first line to the second line.

...<script id="NLohRAMdsC">...
...<script id="QiJHwOFlpL">...

In fact, that commit was automatically created after I pushed a "no-op" change to master (...the only difference was the hashes in git). Therefore, no files in the gh-pages branch needed to be changed.

I would find it helpful when verifying changes and debugging problems if the commits in the gh-pages branch only contained necessary changes.

Is it possible to remove this randomness? If it is somewhat essential, maybe a seed to the underlying generator could be specified in configuration.

[loreanvictor]

It might be possible by fixing here, though I would generally not rely on version controlling / diffing automatically generated files.

EDIT: on further thought, the change is not as trivial.

To elaborate why: the random IDs are basically transport references. Transported content is content that is not rendered at build stage but rather at client side, and transport reference marks the position of such content amongst the rest of the DOM.

Transport references need to be unique, so when they are not fully random, they need to be generated in a manner that their uniqueness is guaranteed during each build. However this would prohibit partial builds, as a transport reference in one rebuilt file could collide with another transport reference in another not-rebuilt file and we'd need to keep track of all of these to propagate the changes.

Right now, partial rebuilds are only used for speeding up local development, but it is also possible to use the same technique to speed up deploys on production as well.

One work-around would be allowing some minor collisions across different pages. The immediate problem with this work-around would be contents of the ToC, which is built once and shared across all pages. Collisions between contents of the ToC and a page would result in buggy behavior, and rebuilding ToC generally means rebuilding every other page (since it is incorporated in every other page).

It would be possible to use a custom namespace for transported content of ToC, ensuring no collision with any other page, and then allowing collision in transport references between other pages. This should work in theory, but I don't have a good feeling about this, i.e. its a lot of added complexity for being able to diff generated files, which shouldn't happen to begin with (you should always compare the source of those generated files not the files themselves). The matter of fact is that we only get in touch with generated files due to how GitHub Pages works, and typically all other JAMStack hosts mask these files, so I don't think we should go through with this.

Keeping the issue open for now for further contemplation.

[TysonMN]

I care less about this now that I don't have a gh-pages branch, which was easily showing me diffs of generated HTML files.

Nevertheless, it is still easier to debug deterministic code that randomized code.

A programmer that has been working for a decade or two longer than me told me about his release and maintenance process, which includes putting the source code, compiler, and compiler-generated files into a compressed folder. Then when he needs to make a change years later, he starts by extracting the compressed folder, compiling the source code with the compiler, and comparing it to the previously generated files. They should be the exact sames files. It would not be possible to have such a meticulous release and maintenance process if the build involved randomness.

Avoiding randomness might help your team debug build issues. For example, it might have been easier to verify the fix for CONNECT-platform/coding-blog#17 if the only difference due to the change that @must made.

...though I would generally not rely on version controlling / diffing automatically generated files.

I think of it like a sanity check. If I changed something in index.mb, then I shouldn't see any changes in 404.html.

If it is somewhat essential, maybe a seed to the underlying generator could be specified in configuration.

It sounds essential (or, at least, coupled) enough to think of it as essential for now.

Transport references need to be unique, so when they are not fully random, they need to be generated in a manner that their uniqueness is guaranteed during each build. However this would prohibit partial builds, as a transport reference in one rebuilt file could collide with another transport reference in another not-rebuilt file and we'd need to keep track of all of these to propagate the changes.

This is not a huge obstacle. Start with a global seed value specified in configuration. Then for each file, you create its own seed by concatenating the global seed value with the relative file path of that file. This file-specific seed then goes into a generator that is only used to randomly generate values (e.g. transport references) in that file.

For simplicity or backwards compatibility, the global seed value in configuration could be optional. If not supplied, then you could either use a default hard-coded value or randomly generate a value. It may sound a bit counter-intuitive to randomly generate the global seed value. After all, there would be added complexity to do everything deterministically but identical randomized behavior because the seed value is still randomly generated. The main difference is that you can specify a seed value if desired in a particular moment. Like when one of my property-based tests fails, I sometimes have to replace the randomness in order to get it to fail again. The other difference is that hard-coding a seed value could be bad because it might cause a collision in transport values with the only user-available fix being to specify their own seed value. By generating the seed randomly, another user-available fix is simply rebuilding.

In sum, any randomized algorithm using a pseudorandom generator can be changed into a deterministic algorithm by passing in the seed value of the generator. I don't expect that making such a change to build is currently a high priority, but someday, the best path forward could be to first make build deterministic and then make some other desired change. If that day comes, I just wanted to make sure you knew that making build deterministic is relatively easy.

[loreanvictor]

I completely sympathize with the sentiment. However, I do believe that the proper solution should be mostly/completely on connective-sdh, instead of opening up its API surface and then fixing stuff in CODEDOC. As a result, I propose moving this discussion to this issue.