Comments (3)
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.
from codedoc.
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.
from codedoc.
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.
from codedoc.
Related Issues (20)
- The build process on gh-actions omits terminal output colors HOT 2
- Theme assets broken when hosted on GitLab Pages HOT 7
- New release with ansi_up fix HOT 4
- Hooking codedoc's router to run code on page change HOT 7
- Search shortcut (CMD+F / ctrl+F) displays the modal n times
- Help with plugin development and publishing on NPM HOT 7
- enhance the underline code block feature to support more languages HOT 2
- support info underlines in codeblocks
- update set-value to a non-vulnerable version
- Support RTL HOT 1
- decreasing the width-size of TOC HOT 2
- Ability to copy multiple lines from codeblocks HOT 7
- Running Codedoc as a container in Raspberry Pi
- GitHub Pages deployment failure after succeeding HOT 3
- Local build not working: TypeError: merge is not a function HOT 4
- Integrated Search missing HOT 2
- Update marked to 4.0.10 to avoid CVE-2022-21680 HOT 1
- Build not working: Non-string value passed to `ts.resolveTypeReferenceDirective` HOT 1
- Pre-build plugin HOT 1
- github action failure HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from codedoc.