Mailing List Archive

Question on HowToContribute Documentation
Hi All,

I am new to Lucene and recently made a small contribution. While figuring
out the contributing process, I felt that the documentation may not be up
to date.

The repository home page <https://github.com/apache/lucene#contributing>
links to this HowToContribute cwiki
<https://cwiki.apache.org/confluence/display/LUCENE/HowToContribute>, which
says that we should upload a patch file with our changes to the relevant
JIRA. However, I observed that contributions could also be made via Github
pull requests that one could raise from a Lucene fork.

Is patch-upload-to-jira, the preferred method of accepting contributions?
Or is there some other documentation that I missed?

The way I understand it, it is easier to review and comment on a pull
request. Perhaps if a reviewer wants to run/benchmark the code change,
downloading and applying a patch file may be easier.

I can help update the documentation if we need to.
We can also include some minor details - like prefixing the PR name with
all caps "LUCENE-#JIRA:", and making an entry in the changes file (these
were things that I had missed). Also, if we make these changes, would we
want to continue using the cwiki page, or just add a contributing.md to the
main repo?

--
- Vigya
Re: Question on HowToContribute Documentation [ In reply to ]
Hi Vigya, I agree, we should describe the github PR workflow. However
patches are still in use, too, so we should have instructions that are
agnostic as to the method, I think. We want to be open to
contributions in any form, as long as we can grok it.

As for the documentation format, I'm not sure. Personally I don't have
a lot of familiarity with the cwiki and I'd prefer in-repo
documentation in .md format. However there is a lot of history in that
wiki we don't want to lose, and splitting documentation in two places
seems like it could lead to more confusion.

I'm not sure what the process is for accepting contributions to the
wiki since it needs a login with permissions for editing and doesn't
support the usual workflow for code submissions. Maybe you could open
an issue and post a plain-text patch :) for the docs as an attachment
there?

-Mike

On Wed, Sep 15, 2021 at 3:35 PM Vigya Sharma <vigya.work@gmail.com> wrote:
>
> Hi All,
>
> I am new to Lucene and recently made a small contribution. While figuring out the contributing process, I felt that the documentation may not be up to date.
>
> The repository home page links to this HowToContribute cwiki, which says that we should upload a patch file with our changes to the relevant JIRA. However, I observed that contributions could also be made via Github pull requests that one could raise from a Lucene fork.
>
> Is patch-upload-to-jira, the preferred method of accepting contributions? Or is there some other documentation that I missed?
>
> The way I understand it, it is easier to review and comment on a pull request. Perhaps if a reviewer wants to run/benchmark the code change, downloading and applying a patch file may be easier.
>
> I can help update the documentation if we need to.
> We can also include some minor details - like prefixing the PR name with all caps "LUCENE-#JIRA:", and making an entry in the changes file (these were things that I had missed). Also, if we make these changes, would we want to continue using the cwiki page, or just add a contributing.md to the main repo?
>
> --
> - Vigya

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org