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 2020/02/26 15:36:15 UTC
[GitHub] [lucene-solr] janhoy opened a new pull request #1291: LUCENE-9016:
RefGuide meta doc for how to publish website
janhoy opened a new pull request #1291: LUCENE-9016: RefGuide meta doc for how to publish website
URL: https://github.com/apache/lucene-solr/pull/1291
Using new git site
----------------------------------------------------------------
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
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene-solr] ctargett commented on a change in pull request #1291:
LUCENE-9016: RefGuide meta doc for how to publish website
Posted by GitBox <gi...@apache.org>.
ctargett commented on a change in pull request #1291: LUCENE-9016: RefGuide meta doc for how to publish website
URL: https://github.com/apache/lucene-solr/pull/1291#discussion_r385841782
##########
File path: solr/solr-ref-guide/src/meta-docs/publish.adoc
##########
@@ -47,54 +49,20 @@ To build the HTML:
[source,bash]
$ ant clean default
+
-This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section <<Publish the Guide>> for steps to produce final production-ready HTML pages.
+This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section <<Publish the Guide without watermark>> for steps to produce final production-ready HTML pages.
. The resulting Guide will be in `solr/build/solr-ref-guide`. The HTML files themselves will be in `solr/build/solr-ref-guide/html-site`.
== Upload to the Website
-// A lot of this was copied from https://wiki.apache.org/lucene-java/ReleaseTodo#Website_.2B-.3D_javadocs. See that section for explanations for why some steps are required.
-
-*Step 1: Update extpaths.txt in CMS Staging*
-
-. Checkout CMS trunk:
-+
-[source,bash]
-$ svn co --depth=immediates https://svn.apache.org/repos/asf/lucene/cms/trunk/content website-source
-+
-* If you already have this repo checked out, you can simply `svn up website-source` to update to the latest revision.
-. `$ cd website-source` (where you just checked out the repo)
-. Add the path for the new Guide version:
-+
-[source,bash]
-$ echo solr/guide/X_Y >> extpaths.txt
-+
-where `X_Y` is the new version (i.e, `7_7`)
-. Commit changes:
-+
-[source,bash]
-$ svn commit -m "Update CMS production sync exceptions for X_Y_Z Guide" extpaths.txt
-
-*Step 2: Push Guide to Website Production*
-
Push the Guide directly to production via Subversion `import` from where you built it.
-You must push it to the path you just added to `extpaths.txt`, so if the path you added was `solr/guide/7_7`, you'll use the path as shown in the below example:
-
[source,bash]
svn -m "Add Ref Guide for Solr 7.7" import <checkoutroot>/solr/build/solr-ref-guide/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/7_7
Confirm you can browse to Guide manually by going to the new URL. For example:
https://lucene.apache.org/solr/guide/7_7
-*Step 3: Push Staging extpaths.txt to Production*
-
-The `extpaths.txt` works by listing paths that should be ignored when the CMS syncs the staging and production repositories. Publishing staging to production will only succeed if the paths listed in `extpaths.txt` exist in production. At the same time, if a path exists in production but not in staging it will be deleted unless it is defined in `extpaths.txt`.
-
-After pushing the content to production, check that the `extpaths.txt` in production includes the proper path to ensure that the Guide is not deleted incorrectly. If it does not exist in production, try to publish the site again to make sure it is updated.
-
-Production URL: https://lucene.apache.org/extpaths.txt
-
-== Publish the Guide
+== Publish the Guide without watermark
Review comment:
Headline case in section titles please....
But not sure why this needed to change? I don't care, just struck me as extraneous and then I realized that the other section heading doesn't say you're publishing a draft so it probably really doesn't matter. I'm the only one who reads this anyway.
----------------------------------------------------------------
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
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene-solr] janhoy merged pull request #1291: LUCENE-9016:
RefGuide meta doc for how to publish website
Posted by GitBox <gi...@apache.org>.
janhoy merged pull request #1291: LUCENE-9016: RefGuide meta doc for how to publish website
URL: https://github.com/apache/lucene-solr/pull/1291
----------------------------------------------------------------
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
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene-solr] janhoy commented on a change in pull request #1291:
LUCENE-9016: RefGuide meta doc for how to publish website
Posted by GitBox <gi...@apache.org>.
janhoy commented on a change in pull request #1291: LUCENE-9016: RefGuide meta doc for how to publish website
URL: https://github.com/apache/lucene-solr/pull/1291#discussion_r385951918
##########
File path: solr/solr-ref-guide/src/meta-docs/publish.adoc
##########
@@ -47,54 +49,20 @@ To build the HTML:
[source,bash]
$ ant clean default
+
-This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section <<Publish the Guide>> for steps to produce final production-ready HTML pages.
+This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section <<Publish the Guide without watermark>> for steps to produce final production-ready HTML pages.
. The resulting Guide will be in `solr/build/solr-ref-guide`. The HTML files themselves will be in `solr/build/solr-ref-guide/html-site`.
== Upload to the Website
-// A lot of this was copied from https://wiki.apache.org/lucene-java/ReleaseTodo#Website_.2B-.3D_javadocs. See that section for explanations for why some steps are required.
-
-*Step 1: Update extpaths.txt in CMS Staging*
-
-. Checkout CMS trunk:
-+
-[source,bash]
-$ svn co --depth=immediates https://svn.apache.org/repos/asf/lucene/cms/trunk/content website-source
-+
-* If you already have this repo checked out, you can simply `svn up website-source` to update to the latest revision.
-. `$ cd website-source` (where you just checked out the repo)
-. Add the path for the new Guide version:
-+
-[source,bash]
-$ echo solr/guide/X_Y >> extpaths.txt
-+
-where `X_Y` is the new version (i.e, `7_7`)
-. Commit changes:
-+
-[source,bash]
-$ svn commit -m "Update CMS production sync exceptions for X_Y_Z Guide" extpaths.txt
-
-*Step 2: Push Guide to Website Production*
-
Push the Guide directly to production via Subversion `import` from where you built it.
-You must push it to the path you just added to `extpaths.txt`, so if the path you added was `solr/guide/7_7`, you'll use the path as shown in the below example:
-
[source,bash]
svn -m "Add Ref Guide for Solr 7.7" import <checkoutroot>/solr/build/solr-ref-guide/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/7_7
Confirm you can browse to Guide manually by going to the new URL. For example:
https://lucene.apache.org/solr/guide/7_7
-*Step 3: Push Staging extpaths.txt to Production*
-
-The `extpaths.txt` works by listing paths that should be ignored when the CMS syncs the staging and production repositories. Publishing staging to production will only succeed if the paths listed in `extpaths.txt` exist in production. At the same time, if a path exists in production but not in staging it will be deleted unless it is defined in `extpaths.txt`.
-
-After pushing the content to production, check that the `extpaths.txt` in production includes the proper path to ensure that the Guide is not deleted incorrectly. If it does not exist in production, try to publish the site again to make sure it is updated.
-
-Production URL: https://lucene.apache.org/extpaths.txt
-
-== Publish the Guide
+== Publish the Guide without watermark
Review comment:
Reverted to old header
----------------------------------------------------------------
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
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene-solr] ctargett commented on a change in pull request #1291:
LUCENE-9016: RefGuide meta doc for how to publish website
Posted by GitBox <gi...@apache.org>.
ctargett commented on a change in pull request #1291: LUCENE-9016: RefGuide meta doc for how to publish website
URL: https://github.com/apache/lucene-solr/pull/1291#discussion_r385842221
##########
File path: solr/solr-ref-guide/src/meta-docs/publish.adoc
##########
@@ -37,6 +37,8 @@ NOTE: Builds are available via https://builds.apache.org/view/L/view/Lucene/[Jen
== Build the DRAFT Guide
+NOTE: After the switch to website in GIT, built by Pelican (https://github.com/apache/lucene-site) we no longer need to update `extpaths.txt`. When the RM changes the `LUCENE_LATEST_RELEASE` variable in https://github.com/apache/lucene-site/blob/master/pelicanconf.py in the website git repo, the default redirect for https://lucene.apache.org/solr/guide/mypage.html will automatically redirect to the latest `X_Y` version. Thus you should always publish a DRAFT guide to that location *before* the release of Solr. Then you can publish a final version later, overwriting the previous.
Review comment:
This paragraph sort of conflates a couple points together IMO.
First, I don't know the value of keeping the idea that there used to be a need to edit the extpaths.txt file - it assumes the reader had a knowledge of how things used to be done, and we know from experience that next to no one does.
Next, the 2nd sentence assumes a knowledge of the binary release process and only links to a script to provide more context. Perhaps it would just be simpler for these two sentences to just say:
"The binary release process [insert link to it] will update the `LUCENE_LATEST_RELEASE` property which will ensure that Ref Guide URLs without a version in the path will automatically redirect to the latest Guide."
And with that simplification, I'm no longer sure it warrants a special NOTE callout style.
Lastly, extpaths.txt being gone and the RM changing a parameter are not the reasons why we push a DRAFT version, so the 2nd-to-last sentence implies that it does inappropriately as far as I understand (unless there is a new dependency that's not reflected here that I'm not aware of?). We push the DRAFT so people can look at it as part of the vote process. That may not be appropriately reflected in the rest of the doc, though, so easy to see how it could be confusing.
----------------------------------------------------------------
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
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene-solr] ctargett commented on a change in pull request #1291:
LUCENE-9016: RefGuide meta doc for how to publish website
Posted by GitBox <gi...@apache.org>.
ctargett commented on a change in pull request #1291: LUCENE-9016: RefGuide meta doc for how to publish website
URL: https://github.com/apache/lucene-solr/pull/1291#discussion_r385842221
##########
File path: solr/solr-ref-guide/src/meta-docs/publish.adoc
##########
@@ -37,6 +37,8 @@ NOTE: Builds are available via https://builds.apache.org/view/L/view/Lucene/[Jen
== Build the DRAFT Guide
+NOTE: After the switch to website in GIT, built by Pelican (https://github.com/apache/lucene-site) we no longer need to update `extpaths.txt`. When the RM changes the `LUCENE_LATEST_RELEASE` variable in https://github.com/apache/lucene-site/blob/master/pelicanconf.py in the website git repo, the default redirect for https://lucene.apache.org/solr/guide/mypage.html will automatically redirect to the latest `X_Y` version. Thus you should always publish a DRAFT guide to that location *before* the release of Solr. Then you can publish a final version later, overwriting the previous.
Review comment:
This paragraph sort of conflates a couple points together IMO.
First, I don't know the value of keeping the idea that there used to be a need to edit the extpaths.txt file - it assumes the reader had a knowledge of how things used to be done, and we know from experience that next to no one does.
Next, the 2nd sentence assumes a knowledge of the binary release process and only links to a script to provide more context. Perhaps it would just be simpler for these two sentences to just say:
"The binary release process [insert link to it] will update the `LUCENE_LATEST_RELEASE` property which will ensure that Ref Guide URLs without a version in the path will automatically redirect to the latest Guide."
And with that simplification, I'm no longer sure it warrants a special NOTE callout style.
Lastly, extpaths.txt being gone and the RM changing a parameter are not the reasons why we push a DRAFT version (as far as I understand - unless there is a new dependency that's not reflected here that I'm not aware of?), so the 2nd-to-last sentence shouldn't imply that it does. We push the DRAFT so people can look at it as part of the vote process. That may not be appropriately reflected in the rest of the doc, though, so easy to see how it could be confusing.
----------------------------------------------------------------
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
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene-solr] ctargett commented on a change in pull request #1291:
LUCENE-9016: RefGuide meta doc for how to publish website
Posted by GitBox <gi...@apache.org>.
ctargett commented on a change in pull request #1291: LUCENE-9016: RefGuide meta doc for how to publish website
URL: https://github.com/apache/lucene-solr/pull/1291#discussion_r385842221
##########
File path: solr/solr-ref-guide/src/meta-docs/publish.adoc
##########
@@ -37,6 +37,8 @@ NOTE: Builds are available via https://builds.apache.org/view/L/view/Lucene/[Jen
== Build the DRAFT Guide
+NOTE: After the switch to website in GIT, built by Pelican (https://github.com/apache/lucene-site) we no longer need to update `extpaths.txt`. When the RM changes the `LUCENE_LATEST_RELEASE` variable in https://github.com/apache/lucene-site/blob/master/pelicanconf.py in the website git repo, the default redirect for https://lucene.apache.org/solr/guide/mypage.html will automatically redirect to the latest `X_Y` version. Thus you should always publish a DRAFT guide to that location *before* the release of Solr. Then you can publish a final version later, overwriting the previous.
Review comment:
This paragraph sort of conflates a couple points together IMO.
First, I don't know the value of keeping the idea that there used to be a need to edit the extpaths.txt file - it assumes the reader had a knowledge of how things used to be done, and we know from experience that next to no one does.
Next, the 2nd sentence assumes a knowledge of the binary release process and only links to a script to provide more context. Perhaps it would just be simpler for these two sentences to just say:
"The binary release process [insert link to it] will update the `LUCENE_LATEST_RELEASE` property which will ensure that Ref Guide URLs without a version in the path will automatically redirect to the latest Guide."
And with that simplification, I'm no longer sure warrants a special NOTE callout style.
Lastly, extpaths.txt being gone and the RM changing a parameter are not the reasons why we push a DRAFT version, so the 2nd-to-last sentence implies that it does inappropriately as far as I understand (unless there is a new dependency that's not reflected here that I'm not aware of?). We push the DRAFT so people can look at it as part of the vote process. That may not be appropriately reflected in the rest of the doc, though, so easy to see how it could be confusing.
----------------------------------------------------------------
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
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene-solr] ctargett commented on issue #1291: LUCENE-9016:
RefGuide meta doc for how to publish website
Posted by GitBox <gi...@apache.org>.
ctargett commented on issue #1291: LUCENE-9016: RefGuide meta doc for how to publish website
URL: https://github.com/apache/lucene-solr/pull/1291#issuecomment-595274181
Sorry, I approved this and then looked at why precommit failed and there is still 1 page reference that is incorrect (since you changed the section title back to what it was originally).
----------------------------------------------------------------
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
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene-solr] ctargett commented on a change in pull request #1291:
LUCENE-9016: RefGuide meta doc for how to publish website
Posted by GitBox <gi...@apache.org>.
ctargett commented on a change in pull request #1291: LUCENE-9016: RefGuide meta doc for how to publish website
URL: https://github.com/apache/lucene-solr/pull/1291#discussion_r388348872
##########
File path: solr/solr-ref-guide/src/meta-docs/publish.adoc
##########
@@ -47,61 +47,26 @@ To build the HTML:
[source,bash]
$ ant clean default
+
-This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section <<Publish the Guide>> for steps to produce final production-ready HTML pages.
+This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section <<Publish the Guide without watermark>> for steps to produce final production-ready HTML pages.
. The resulting Guide will be in `solr/build/solr-ref-guide`. The HTML files themselves will be in `solr/build/solr-ref-guide/html-site`.
Review comment:
Since you changed the heading this refers to back to its original, this reference should be changed too. This is why precommit failed.
----------------------------------------------------------------
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
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene-solr] ctargett commented on a change in pull request #1291:
LUCENE-9016: RefGuide meta doc for how to publish website
Posted by GitBox <gi...@apache.org>.
ctargett commented on a change in pull request #1291: LUCENE-9016: RefGuide meta doc for how to publish website
URL: https://github.com/apache/lucene-solr/pull/1291#discussion_r385842221
##########
File path: solr/solr-ref-guide/src/meta-docs/publish.adoc
##########
@@ -37,6 +37,8 @@ NOTE: Builds are available via https://builds.apache.org/view/L/view/Lucene/[Jen
== Build the DRAFT Guide
+NOTE: After the switch to website in GIT, built by Pelican (https://github.com/apache/lucene-site) we no longer need to update `extpaths.txt`. When the RM changes the `LUCENE_LATEST_RELEASE` variable in https://github.com/apache/lucene-site/blob/master/pelicanconf.py in the website git repo, the default redirect for https://lucene.apache.org/solr/guide/mypage.html will automatically redirect to the latest `X_Y` version. Thus you should always publish a DRAFT guide to that location *before* the release of Solr. Then you can publish a final version later, overwriting the previous.
Review comment:
This paragraph sort of conflates a couple points together IMO.
First, I don't know the value of keeping the idea that there used to be a need to edit the extpaths.txt file actually provides much value - it assumes the reader had a knowledge of how things used to be done, and we know from experience that next to no one does.
Next, the 2nd sentence assumes a knowledge of the binary release process and only links to a script to provide more context. Perhaps it would just be simpler for these two sentences to just say:
"The binary release process <<link>> will update the `LUCENE_LATEST_RELEASE` property which will ensure that Ref Guide URLs without a version in the path will automatically redirect to the latest Guide."
And with that simplification, I'm no longer sure warrants a special NOTE callout style.
Lastly, extpaths.txt being gone and the RM changing a parameter are not the reasons why we push a DRAFT version, so the 2nd-to-last sentence implies that it does inappropriately as far as I understand (unless there is a new dependency that's not reflected here that I'm not aware of?). We push the DRAFT so people can look at it as part of the vote process. That may not be appropriately reflected in the rest of the doc, though, so easy to see how it could be confusing.
----------------------------------------------------------------
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
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene-solr] janhoy commented on a change in pull request #1291:
LUCENE-9016: RefGuide meta doc for how to publish website
Posted by GitBox <gi...@apache.org>.
janhoy commented on a change in pull request #1291: LUCENE-9016: RefGuide meta doc for how to publish website
URL: https://github.com/apache/lucene-solr/pull/1291#discussion_r385951802
##########
File path: solr/solr-ref-guide/src/meta-docs/publish.adoc
##########
@@ -37,6 +37,8 @@ NOTE: Builds are available via https://builds.apache.org/view/L/view/Lucene/[Jen
== Build the DRAFT Guide
+NOTE: After the switch to website in GIT, built by Pelican (https://github.com/apache/lucene-site) we no longer need to update `extpaths.txt`. When the RM changes the `LUCENE_LATEST_RELEASE` variable in https://github.com/apache/lucene-site/blob/master/pelicanconf.py in the website git repo, the default redirect for https://lucene.apache.org/solr/guide/mypage.html will automatically redirect to the latest `X_Y` version. Thus you should always publish a DRAFT guide to that location *before* the release of Solr. Then you can publish a final version later, overwriting the previous.
Review comment:
Agree. I added a similar text at the bottom of the page.
----------------------------------------------------------------
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
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene-solr] ctargett commented on issue #1291: LUCENE-9016:
RefGuide meta doc for how to publish website
Posted by GitBox <gi...@apache.org>.
ctargett commented on issue #1291: LUCENE-9016: RefGuide meta doc for how to publish website
URL: https://github.com/apache/lucene-solr/pull/1291#issuecomment-592656314
Sorry for the delay, I meant to review the other day and then it slipped my mind.
I left a couple comments inline. Mostly I think we don't need to mention extpaths.txt at all anymore (we have old versions if we need to remember it), and thought of an easier way to clarify the change in the process (as I understand it, I haven't followed the issues religiously, so maybe missed some details).
----------------------------------------------------------------
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
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org