[
https://issues.apache.org/jira/browse/SOLR-15682?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17574358#comment-17574358
]
Jan Høydahl commented on SOLR-15682:
------------------------------------
I looked around other Apache projects with CONTRIBUTING files, and you find
every variation out there. Some focus on code contributions, others are 50
pages long developer gudes. The Spark one seems to have one goal - to reduce
the number of low-quality contributions and PRs :) etc.
One that I think has a nice balance between necessary information and brewity
is Apache Doris' CONTRIBUTING file:
[https://github.com/apache/doris/blob/master/CONTRIBUTING.md]. It starts with a
warm welcome, followed by pointers to mailing lists etc, and a short intro to
the various modules and documentation of the project. Then they describe
briefly, with links to more in-dept docs, how to contribute documentation, how
to report bugs, and finally code contribution.
We can generously link to both webpage (for code-of-conduct etc) and to
/dev-guide/ or even /help/, and imo, instead of writing three parargraphs on a
topic in CONTRIBUTING, it is better to create a new dev-docs file to link to,
with just a few sentences summary in CONTRIBUTING.
PS: Lucene also has a CONTRIBUTING file we can borrow from, but I feel it is
currently more of a code contribution guide than a general project contribution
guide...
> Add a CONTRIBUTING file
> -----------------------
>
> Key: SOLR-15682
> URL: https://issues.apache.org/jira/browse/SOLR-15682
> Project: Solr
> Issue Type: Task
> Components: documentation
> Reporter: Jan Høydahl
> Assignee: Eric Pugh
> Priority: Major
>
> As [discussed in
> dev-list|https://lists.apache.org/thread.html/raa4a0538fb7b32ebf4ec2d9a26bf04680b001b2723b70633eb06bcb4%40%3Cdev.solr.apache.org%3E],
> we should add a {{CONTRIBUTING.md}} file to serve as the first introduction
> for how to contribute:
> {quote}Currently we have our wiki page
> [HowToContribute|https://cwiki.apache.org/confluence/display/SOLR/HowToContribute],
> which is linked from README.md. But there has been complaints lately that
> this wiki page is old and needlessly complex / long.
> Some benefits of a CONTRIBUTING file are:
> * People immediately understand what to expect when they see the file
> (visibility)
> * GitHub has [built-in support for
> it|https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors]
> and will display a link when someone opens a PR.
> * We can author it from scratch, with better, clearer structure
> The file can of course rely on linking to dev-docs, wiki and website as
> needed, so the file can likely stay quite compact.
> {quote}
>
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
