LUCENE-9916: add a simple regeneration help doc#73
Conversation
|
I have a question: why do we need this "tidy" at end of command line? If it is always required, it could be triggered automatically? I know this is unrelated to the documentation issue, but whenever I see any of those instructions, this puts questions in my eyes: 🤔 |
|
|
||
| Regenerate code: | ||
|
|
||
| gradlew regenerate tidy |
There was a problem hiding this comment.
I would indexnt those lines. Maybe use Markdown for whole help files?
There was a problem hiding this comment.
FYI I followed the style of existing help docs which do not indent, see tests.txt. I would say +1 to markdown as the current format is alien, and markdown would give good rendering on github?
There was a problem hiding this comment.
I hate those markup formats and live in txt world... Also, these files are sourced (and printed) as part of helpXXX tasks which you can invoke from gradlew. Don't know if this matters (I'm sure there is a plugin somewhere that renders them into ascii console opcodes...).
There was a problem hiding this comment.
Markdown is a good compromise. I just think we should use as minimal as possible, but e.g. make code parts inside code blocks or indent, so its blockquoted(sourceformatted automatically.
I don't want full featured Markdown :-)
dweiss
left a comment
dweiss
left a comment
There was a problem hiding this comment.
If you use regenerate ten I tried to make tidy an automatic follow-up. So in theory (and I think in practice at the moment) you can run ./gradlew regenerate --rerun-tasks and it should result in no differences.
|
|
||
| gradlew --rerun-tasks regenerate tidy | ||
|
|
||
| Force-regenerate code, except for one tokenizer which is extremely slow: |
There was a problem hiding this comment.
Most regeneration tasks are incremental at the moment - they do sense if they need to run or not. There should be a big red "last resort" option in this help file because in 99% of cases this should do the job: gradlew regenerate. That's it. Skips over tasks that have the same inputs/ outputs, regenerates and tidies up everything else. I've tested it on Linux and Windows and it really does work. The trouble you fell into today was caused by the fact that you use the low-level regeneration task and regenerate has all sorts of tweaks to make those tasks incremental and clean up formatting, etc.
There was a problem hiding this comment.
An example of when --rerun-tasks is useful is when you tweak the code of the generation task itself (not the inputs/outputs but the task itself).
There was a problem hiding this comment.
I figured out that gradle also rexecutes tasks if you change its source file (at least in the past this worked). I tested this at least when developing the renderJavadocs classes.
|
Leave this patch open, Robert. There is one more non-trivial bit (checksum saving) that I need to explain there - I'll do it once I get back home. |
|
sure, please anyone push improvements, i just wanted to get it started. |
… regeneration task). Sorry for being verbose. Maybe somebody will read it. :)
|
I pushed a commit - sorry for being verbose. Hope this will helps you (and others) understand how I think it should work. Not every task is incremental yet (and I didn't clarify that). |
|
super-helpful, thank you @dweiss ! |
3 participants
This probably isn't most efficient or the best, but its a start.
Some notes:
--rerun-tasksthe tidy is unnecessarily rerun even if its not necessary, which is actually quite slow. Is thetidytask really necessary or is it automatically/more efficiently done as some prerequisite ofregenerate?