You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@lucene.apache.org by GitBox <gi...@apache.org> on 2021/04/08 13:39:55 UTC
[GitHub] [lucene] rmuir opened a new pull request #73: LUCENE-9916: add a simple regeneration help doc
rmuir opened a new pull request #73:
URL: https://github.com/apache/lucene/pull/73
This probably isn't most efficient or the best, but its a start.
Some notes:
* Using these steps to "force regenerate" results in local diffs. These look to be hashmap ordering differences or similar. We should fix these so that regeneration is fully idempotent?
* Might not be the most efficient, for example when using `--rerun-tasks` the tidy is unnecessarily rerun even if its not necessary, which is actually quite slow. Is the `tidy` task really necessary or is it automatically/more efficiently done as some prerequisite of `regenerate`?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] rmuir merged pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
rmuir merged pull request #73:
URL: https://github.com/apache/lucene/pull/73
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] rmuir commented on pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
rmuir commented on pull request #73:
URL: https://github.com/apache/lucene/pull/73#issuecomment-816171377
super-helpful, thank you @dweiss !
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] uschindler commented on pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
uschindler commented on pull request #73:
URL: https://github.com/apache/lucene/pull/73#issuecomment-815870339
I have a question: why do we need this "tidy" at end of command line? If it is always required, it could be triffered automatically?
I know this is unrelated to the documentation issue, but whenever I see any of those instructions, this puts questions in my eyes: 🤔
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] dweiss commented on pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
dweiss commented on pull request #73:
URL: https://github.com/apache/lucene/pull/73#issuecomment-815914300
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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] dweiss commented on a change in pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
dweiss commented on a change in pull request #73:
URL: https://github.com/apache/lucene/pull/73#discussion_r609808709
##########
File path: help/regeneration.txt
##########
@@ -0,0 +1,23 @@
+Regeneration
+============
+
+Lucene makes use of some generated code (e.g. jflex tokenizers).
+
+Examples below assume cwd at the gradlew script in the top directory of
+the project's checkout.
+
+
+Generic regeneration commands
+------------------------------
+
+Regenerate code:
+
+gradlew regenerate tidy
+
+Force-regenerate code, even when it isn't necessary:
+
+gradlew --rerun-tasks regenerate tidy
+
+Force-regenerate code, except for one tokenizer which is extremely slow:
Review 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).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] dweiss commented on a change in pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
dweiss commented on a change in pull request #73:
URL: https://github.com/apache/lucene/pull/73#discussion_r609807318
##########
File path: help/regeneration.txt
##########
@@ -0,0 +1,23 @@
+Regeneration
+============
+
+Lucene makes use of some generated code (e.g. jflex tokenizers).
+
+Examples below assume cwd at the gradlew script in the top directory of
+the project's checkout.
+
+
+Generic regeneration commands
+------------------------------
+
+Regenerate code:
+
+gradlew regenerate tidy
+
+Force-regenerate code, even when it isn't necessary:
+
+gradlew --rerun-tasks regenerate tidy
+
+Force-regenerate code, except for one tokenizer which is extremely slow:
Review 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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] uschindler edited a comment on pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
uschindler edited a comment on pull request #73:
URL: https://github.com/apache/lucene/pull/73#issuecomment-815870339
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: 🤔
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] dweiss commented on pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
dweiss commented on pull request #73:
URL: https://github.com/apache/lucene/pull/73#issuecomment-816110667
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).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] rmuir commented on a change in pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
rmuir commented on a change in pull request #73:
URL: https://github.com/apache/lucene/pull/73#discussion_r609772375
##########
File path: help/regeneration.txt
##########
@@ -0,0 +1,23 @@
+Regeneration
+============
+
+Lucene makes use of some generated code (e.g. jflex tokenizers).
+
+Examples below assume cwd at the gradlew script in the top directory of
+the project's checkout.
+
+
+Generic regeneration commands
+------------------------------
+
+Regenerate code:
+
+gradlew regenerate tidy
Review 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?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] uschindler commented on a change in pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
uschindler commented on a change in pull request #73:
URL: https://github.com/apache/lucene/pull/73#discussion_r609817750
##########
File path: help/regeneration.txt
##########
@@ -0,0 +1,23 @@
+Regeneration
+============
+
+Lucene makes use of some generated code (e.g. jflex tokenizers).
+
+Examples below assume cwd at the gradlew script in the top directory of
+the project's checkout.
+
+
+Generic regeneration commands
+------------------------------
+
+Regenerate code:
+
+gradlew regenerate tidy
+
+Force-regenerate code, even when it isn't necessary:
+
+gradlew --rerun-tasks regenerate tidy
+
+Force-regenerate code, except for one tokenizer which is extremely slow:
Review 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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] dweiss commented on a change in pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
dweiss commented on a change in pull request #73:
URL: https://github.com/apache/lucene/pull/73#discussion_r609801705
##########
File path: help/regeneration.txt
##########
@@ -0,0 +1,23 @@
+Regeneration
+============
+
+Lucene makes use of some generated code (e.g. jflex tokenizers).
+
+Examples below assume cwd at the gradlew script in the top directory of
+the project's checkout.
+
+
+Generic regeneration commands
+------------------------------
+
+Regenerate code:
+
+gradlew regenerate tidy
Review 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...).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] rmuir commented on pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
rmuir commented on pull request #73:
URL: https://github.com/apache/lucene/pull/73#issuecomment-816036750
sure, please anyone push improvements, i just wanted to get it started.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] uschindler commented on a change in pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
uschindler commented on a change in pull request #73:
URL: https://github.com/apache/lucene/pull/73#discussion_r609763034
##########
File path: help/regeneration.txt
##########
@@ -0,0 +1,23 @@
+Regeneration
+============
+
+Lucene makes use of some generated code (e.g. jflex tokenizers).
+
+Examples below assume cwd at the gradlew script in the top directory of
+the project's checkout.
+
+
+Generic regeneration commands
+------------------------------
+
+Regenerate code:
+
+gradlew regenerate tidy
Review comment:
I would indexnt those lines. Maybe use Markdown for whole help files?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] uschindler commented on a change in pull request #73: LUCENE-9916: add a simple regeneration help doc
Posted by GitBox <gi...@apache.org>.
uschindler commented on a change in pull request #73:
URL: https://github.com/apache/lucene/pull/73#discussion_r609819216
##########
File path: help/regeneration.txt
##########
@@ -0,0 +1,23 @@
+Regeneration
+============
+
+Lucene makes use of some generated code (e.g. jflex tokenizers).
+
+Examples below assume cwd at the gradlew script in the top directory of
+the project's checkout.
+
+
+Generic regeneration commands
+------------------------------
+
+Regenerate code:
+
+gradlew regenerate tidy
Review 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 :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org