Solr documentation questions

["Arrieta, Alejandro" <aa...@perrinsoftware.com>]

Hello Team,

I want to help with Solr documentation and  I have some newbie questions:

-Changes in documentation in Solr git repo, do they  need a doc bug ticket
filled?
-If making more than one change to documentation, do you need one PR for
all of them or each change on a separate PR. If a doc bug ticket is needed
one per PR?
-Are there other test(s) to run apart from compiling, seeing that
documentation finished correctly and checking your change display correctly
in your local copy?
-For proposed changes in the Solr wiki, how is this handled? Does anyone
check the changes before publishing them? How do I get edit permits?

I see the Solr git repo has these branches:
main -> generates Solr 10 ( not yet released ) documentation
branch_9x -> generates Solr 9.2 (not yet released) documentation
If I want to make a change in documentation, where is the correct branch to
do it? main (Solr 10), branch_9x (Solr 9.2), both?

Kind Regards,
Alejandro Arrieta Rios

Re: Solr documentation questions

[Houston Putman <ho...@apache.org>]

Hey Alejandro!

It would be great to get some help with the docs!!

Are there other test(s) to run apart from compiling, seeing that
> documentation finished correctly and checking your change display correctly
> in your local copy?
>

The following command will build a local site for you to look around. (and
fail on any antora compilation issues)

gradle buildLocalSite


The following command will ensure that all links in the ref-guide are
valid, both inter-ref-guide links and links to the javaDocs and lucene
javaDocs.

gradle checkSiteLinks


As Kevin said, "gradlew check -x test" will run "buildLocalSite" and
"checkSiteLinks" for you.

- Houston

On Wed, Mar 8, 2023 at 9:31 AM Kevin Risden <kr...@apache.org> wrote:

> - Not all documentation changes need a Jira. If its a big change like
> adding a new page/section it might be worth a Jira to help call it out in
> the release notes (solr/CHANGES.txt)
> - Depending on the scope of the multiple changes - it could be one PR or
> could be broken up.
> - "./gradlew check -x test" should do most of the validation steps aside
> from seeing how it looks - there is probably a more specific Gradle task as
> well that is isolated to documentation, but that command will do a lot of
> checks. The PR will also do a lot of the same checks.
> - The Solr wiki most likely shouldn't be the source of truth anymore (I'm
> sure there are exceptions) I thought most stuff was migrated to the
> documentation.
> - Focus on the main branch and then as needed will be backported to other
> appropriate branches (ie: branch_9x) - no need to separate PRs usually.
>
> Some examples of other documentation PRs that haven't been merged yet -
> https://github.com/apache/solr/pulls/jebnix - no Jira but have some nice
> cleanup.
>
> Kevin Risden
>
>
> On Wed, Mar 8, 2023 at 9:23 AM Arrieta, Alejandro <
> aarrieta@perrinsoftware.com> wrote:
>
> > Hello Team,
> >
> > I want to help with Solr documentation and  I have some newbie questions:
> >
> > -Changes in documentation in Solr git repo, do they  need a doc bug
> ticket
> > filled?
> > -If making more than one change to documentation, do you need one PR for
> > all of them or each change on a separate PR. If a doc bug ticket is
> needed
> > one per PR?
> > -Are there other test(s) to run apart from compiling, seeing that
> > documentation finished correctly and checking your change display
> correctly
> > in your local copy?
> > -For proposed changes in the Solr wiki, how is this handled? Does anyone
> > check the changes before publishing them? How do I get edit permits?
> >
> > I see the Solr git repo has these branches:
> > main -> generates Solr 10 ( not yet released ) documentation
> > branch_9x -> generates Solr 9.2 (not yet released) documentation
> > If I want to make a change in documentation, where is the correct branch
> to
> > do it? main (Solr 10), branch_9x (Solr 9.2), both?
> >
> > Kind Regards,
> > Alejandro Arrieta Rios
> >
>

Re: Solr documentation questions

[Kevin Risden <kr...@apache.org>]

- Not all documentation changes need a Jira. If its a big change like
adding a new page/section it might be worth a Jira to help call it out in
the release notes (solr/CHANGES.txt)
- Depending on the scope of the multiple changes - it could be one PR or
could be broken up.
- "./gradlew check -x test" should do most of the validation steps aside
from seeing how it looks - there is probably a more specific Gradle task as
well that is isolated to documentation, but that command will do a lot of
checks. The PR will also do a lot of the same checks.
- The Solr wiki most likely shouldn't be the source of truth anymore (I'm
sure there are exceptions) I thought most stuff was migrated to the
documentation.
- Focus on the main branch and then as needed will be backported to other
appropriate branches (ie: branch_9x) - no need to separate PRs usually.

Some examples of other documentation PRs that haven't been merged yet -
https://github.com/apache/solr/pulls/jebnix - no Jira but have some nice
cleanup.

Kevin Risden


On Wed, Mar 8, 2023 at 9:23 AM Arrieta, Alejandro <
aarrieta@perrinsoftware.com> wrote:

> Hello Team,
>
> I want to help with Solr documentation and  I have some newbie questions:
>
> -Changes in documentation in Solr git repo, do they  need a doc bug ticket
> filled?
> -If making more than one change to documentation, do you need one PR for
> all of them or each change on a separate PR. If a doc bug ticket is needed
> one per PR?
> -Are there other test(s) to run apart from compiling, seeing that
> documentation finished correctly and checking your change display correctly
> in your local copy?
> -For proposed changes in the Solr wiki, how is this handled? Does anyone
> check the changes before publishing them? How do I get edit permits?
>
> I see the Solr git repo has these branches:
> main -> generates Solr 10 ( not yet released ) documentation
> branch_9x -> generates Solr 9.2 (not yet released) documentation
> If I want to make a change in documentation, where is the correct branch to
> do it? main (Solr 10), branch_9x (Solr 9.2), both?
>
> Kind Regards,
> Alejandro Arrieta Rios
>