nick-boss-tech opened a new pull request, #5212: URL: https://github.com/apache/solr/pull/5212
🤖 *AI text below* 🤖 *(posted on behalf of Nick Shanin)* https://issues.apache.org/jira/browse/SOLR-18577 ## What happens today **Seven references in the contributor-facing docs and one javadoc are dead, and several workflow statements in the same docs no longer match the build or the repository.** The Slack sign-up address https://s.apache.org/solr-slack appears in [CONTRIBUTING.md](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/CONTRIBUTING.md#L24), [README.md](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/README.md#L76), [solr/packaging/README.txt](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/solr/packaging/README.txt#L50) and the admin UI ([index.html](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/solr/webapp/web/index.html#L273)). It redirects to a Community Inviter page that answers 404: the invite service has shut down, and its successor service has no page for the workspace. Also dead: the packaging README's project site address [https://solr.apache.org/solr](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/solr/packaging/README.txt#L25) (404); the [personal page](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/dev-docs/how-to-contribute.adoc#L21) the contributor guide cites for not emailing committers (404, also on the successor host for Apache personal pages); the [help directory](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/dev-docs/solr-source-code.adoc#L82), which no longer exists in the tree; the PMC chair guide's [GitHub reference](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/dev-docs/pmc-chair.adoc#L47) (redirects to a wiki page answering 404); the Git guide's [crash course](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/dev-docs/git.adoc#L24) (403); and the [shortlink](https://github.com/apache /solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/solr/core/src/java/org/apache/solr/search/facet/RelatednessAgg.java#L750) in the RelatednessAgg javadoc (its target answers 400 on the current list archive). Stale content: the changelog guide gives the fragment folder as [`solr/changelog/unreleased/`](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/dev-docs/changelog.adoc#L8), but no `solr/changelog` directory exists; fragments live in `changelog/unreleased/` at the repository root. The JVM guide's test example points at [a JDK 14 install](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/dev-docs/jvms.adoc#L11); the build's minimum Java version is 21. The FAQ says Error Prone runs [on Jenkins](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/dev-docs/FAQ.adoc#L61) and describes [Sonatype Lift](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/dev-docs/FAQ.adoc#L65) as reviewing pull requests; PR checks run as GitHub Actions and no Lift configuration exists in this repository. Two pages point at the removed `help/` directory for the Gradle help texts ([source code guide](http s://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/dev-docs/solr-source-code.adoc#L25), [dev-docs index](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/dev-docs/README.adoc#L6)); those texts live in `dev-docs/gradle-help/`. The contributor guide also omits that a first-time contributor's workflow runs wait for a maintainer's approval. Every other external address in these docs was requested directly on 2026-10-22 and 2026-10-23, including a full sweep of dev-docs (42 files, 182 unique addresses). The seven above are the dead ones; the only other non-answers are behind ASF login walls (reporter.apache.org, whimsy, the private PMC area), which is by design. ## What this change does **Each dead reference now points at a live address carrying the same content or its current canonical home, and the stale statements are corrected. Thirteen files change; the only code file touched is a javadoc comment.** The four Slack references now point at the project's #solr-dev channel in the ASF Slack workspace ([CONTRIBUTING.md](https://github.com/nick-boss-tech/solr/blob/2178e9d70c3a9cfd5e83b6d59315d50682cbc43e/CONTRIBUTING.md#L24), [README.md](https://github.com/nick-boss-tech/solr/blob/2178e9d70c3a9cfd5e83b6d59315d50682cbc43e/README.md#L76), [README.txt](https://github.com/nick-boss-tech/solr/blob/2178e9d70c3a9cfd5e83b6d59315d50682cbc43e/solr/packaging/README.txt#L50), [index.html](https://github.com/nick-boss-tech/solr/blob/2178e9d70c3a9cfd5e83b6d59315d50682cbc43e/solr/webapp/web/index.html#L273)), the channel address the project publishes on its [community page](https://solr.apache.org/community.html#mailing-lists-chat) and that README's Get Involved section already uses. The site address in the packaging README is now the site root, https://solr.apache.org/ ([README.txt](https://github.com/nick-boss-tech/solr/blob/2178e9d70c3a9cfd5e83b6d59315d50682cbc43e/solr/packaging/README.txt#L25) ). The contributor guide cites the ASF email tips page instead of the dead personal page ([how-to-contribute.adoc](https://github.com/nick-boss-tech/solr/blob/2178e9d70c3a9cfd5e83b6d59315d50682cbc43e/dev-docs/how-to-contribute.adoc#L21)); it carries the same guidance: "Do not send development or use questions in private emails. Keep the discussion on the mailing list." The source code guide points at the dev-docs directory ([solr-source-code.adoc](https://github.com/nick-boss-tech/solr/blob/2178e9d70c3a9cfd5e83b6d59315d50682cbc43e/dev-docs/solr-source-code.adoc#L82)). The PMC chair guide's see-also points at GitBox ([pmc-chair.adoc](https://github.com/nick-boss-tech/solr/blob/2178e9d70c3a9cfd5e83b6d59315d50682cbc43e/dev-docs/pmc-chair.adoc#L47)). The Git guide's crash course bullet points at the Pro Git chapter for SVN users ([git.adoc](https://github.com/nick-boss-tech/solr/blob/2178e9d70c3a9cfd5e83b6d59315d50682cbc43e/dev-docs/git.adoc#L24)), and its beginners bullet, which pointe d at a "let me google that for you" joke link, now points at the Git Tutorial on git-scm.com ([git.adoc](https://github.com/nick-boss-tech/solr/blob/620a5601bcf/dev-docs/git.adoc#L25)). The RelatednessAgg citation links the cited message in the MARC archive, which resolves its Message-ID ([RelatednessAgg.java](https://github.com/nick-boss-tech/solr/blob/2178e9d70c3a9cfd5e83b6d59315d50682cbc43e/solr/core/src/java/org/apache/solr/search/facet/RelatednessAgg.java#L750)). The content corrections: - Changelog guide: fragment folder given as `changelog/unreleased/` at the repository root, the layout drawing matches the folders that exist, and the task name is spelled `writeChangelog` throughout ([changelog.adoc](https://github.com/nick-boss-tech/solr/blob/8ae42dc5e89/dev-docs/changelog.adoc#L8)). - JVM guide: the example now points at a JDK 25 install ([jvms.adoc](https://github.com/nick-boss-tech/solr/blob/8ae42dc5e89/dev-docs/jvms.adoc#L11)). - FAQ: Jenkins no longer named for Error Prone, the Sonatype Lift paragraph is removed, and the frontend answer uses `./gradlew dev` like the rest of the docs ([FAQ.adoc](https://github.com/nick-boss-tech/solr/blob/8ae42dc5e89/dev-docs/FAQ.adoc#L61)). - Source code guide and dev-docs index: the Gradle help texts are located in `dev-docs/gradle-help`; the source code guide's `check` sentence is completed ([solr-source-code.adoc](https://github.com/nick-boss-tech/solr/blob/8ae42dc5e89/dev-docs/solr-source-code.adoc#L25), [README.adoc](https://github.com/nick-boss-tech/solr/blob/8ae42dc5e89/dev-docs/README.adoc#L6)). - Contributor guide: step 4 now says a first contribution's workflow runs need a maintainer's approval before they start ([how-to-contribute.adoc](https://github.com/nick-boss-tech/solr/blob/8ae42dc5e89/dev-docs/how-to-contribute.adoc#L40)). ## Proof **Every address named here was requested directly on 2026-10-22 and 2026-10-23.** - Slack: old address 302 to the Community Inviter page, which answers 404. New address is the channel the project's community page publishes; it resolves into the ASF Slack workspace. - Site: https://solr.apache.org/solr answers 404. New: https://solr.apache.org/ answers 200. - Personal page: answers 404. New: https://www.apache.org/dev/contrib-email-tips.html answers 200. - Help directory: https://github.com/apache/solr/blob/main/help answers 404 and no `help` directory exists in the tree. New: the dev-docs tree answers 200. - Infra reference: redirects to a wiki page answering 404. New: https://gitbox.apache.org/ answers 200. - Crash course: answers 403. New: the Pro Git chapter answers 200. - Shortlink: redirects to an old-format archive address answering 400. New: the MARC address resolves the cited Message-ID to the message itself. - Beginners bullet: the old address (lmgtfy.com) answers 200 and is replaced on tone, not because it is dead. New: https://git-scm.com/docs/gittutorial answers 200. - Content corrections checked against the tree on 2026-10-23: `gradle/changelog.gradle` defines `writeChangelog` writing to `changelog/unreleased/`; `gradle/libs.versions.toml` sets the minimum Java version to 21; no `.lift.toml` or other Lift configuration exists in the repository; `.github/workflows/gradle-precommit.yml` runs `check -x test` as a GitHub Action on pull requests. - A search of the changed files at the new head finds no remaining occurrence of any of the seven dead addresses. `./gradlew :solr:core:tidy` runs clean on the branch, and `:solr:core:check -x test` passes at head `8ae42dc5e89`, verified 2026-10-23. ## A choice to check **Recommendation: point these pages at the ASF #solr-dev channel, as this PR does, rather than removing the Slack references.** The old address was a public sign-up for a community Slack workspace, and no public sign-up exists today: the invite service has shut down and its successor has no page for the workspace. The project's community page is not a fallback; it sends readers to the same dead address. What exists is the ASF workspace's #solr-dev channel, which ASF members enter directly and other contributors enter as invited guests, a route ASF Infra documents. The project's own dev docs send readers to [that channel for detailed questions](https://github.com/apache/solr/blob/b73f03976fa17b857bc0a81bc8af2c6b1c31e0bb/dev-docs/IDEs.adoc#L6). The deciding question: should these pages promise only destinations any reader can walk into unaided? If so, the Slack lines should come out of all four pages until a public sign-up exists again, leaving IRC as the open chat. If a pointer to the room the developers actually use is worth the guest step, the channel link is the destination. These pages exist to help readers reach the project and the developers are in that channel, so the PR keeps the pointer. Reviewers who weigh the guest step differently would land on removal. ## Limits - The same dead Slack address appears on the project website (the community page in the solr-site repository). That page is outside this PR. - Whether the community workspace behind the old invite page still operates could not be confirmed; only its invite service is verifiably gone. - Three replacements are the current canonical home rather than the same content at a new address: GitBox for the retired Infra wiki page, the Pro Git chapter for the crash course, and the dev-docs directory for the removed help directory. - The content pass covered the contributor-facing docs (contributor guide, Git guide, source code guide, IDE and JVM guides, FAQ, changelog guide, dev-docs index, CONTRIBUTING.md). Maintainer process docs were not audited for content. ## Checklist - [x] I have reviewed the guidelines for How to Contribute and my code conforms to the standards described there to the best of my ability. - [x] I have created a Jira issue and added the issue ID to my pull request title. SOLR-18577 - [x] I have given Solr maintainers access to contribute to my PR branch. - [x] I have developed this patch against the `main` branch. - [ ] I have run `./gradlew check`. **Not run in full:** link and wording changes plus one javadoc comment; `:solr:core:tidy` runs clean and `:solr:core:check -x test` passes at the head. - [ ] I have added tests for my changes. **Not applicable.** - [ ] I have added documentation for the Reference Guide. **Not applicable:** this change is to the community-facing docs themselves. - [ ] I have added a changelog entry. **Not added:** not a change to Solr's behavior. *AI-generated description. Nick Shanin directed the work and takes responsibility for this contribution.* -- 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. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
