Propose changes to the Reporting Issues page

[Nathan Hartman <ha...@gmail.com>]

From time to time we get account requests for Jira from members of the
community. There is such a request now.

Historically we have declined these Jira account requests and directed
requesters to discuss their issues at the mailing list first.

This wastes everyone's time and efforts, so I would like to improve
the Reporting Issues page [1] to hopefully avoid this:

I recommend to remove everything until Handy Dandy Issue Tracker
Queries and replace it with two new subsections:

[[[

Report A Bug
============

If you believe you have encountered a bug in Subversion, please write
to the Subversion Users mailing list (users@subversion.apache.org) and
provide at least the following information in your message:

* What steps led to the issue.

* The expected outcome.

* The actual outcome.

* The release and/or revision of Subversion. You can copy and paste
the output of 'svn --version' or 'svn --version --verbose'. If the
issue involves client and server, it may be helpful to provide the
versions of both.

* If you built Subversion yourself, the compiler and configuration
options used.

* Any customizations which could be relevant.

* Your operating system.

* Any other details you believe are relevant. The more detail you can
provide, the more likely it is that someone can help. If you can find
similar bugs in the issue tracker (see below), please mention those as
well.

See Mailing Lists (https://subversion.apache.org/mailing-lists.html)
for how to subscribe, unsubscribe, and send email to the users@
mailing list.

Request a New Feature
=====================

Subversion is an open source project developed and supported by
volunteers. This means you can contribute to Subversion! It also means
that any features you request are likely to become reality only if you
are willing to do the development effort.

We strongly recommend to discuss any new feature ideas at the
Subversion Developers mailing list (dev@subversion.apache.org).

See Mailing Lists (https://subversion.apache.org/mailing-lists.html)
for how to subscribe, unsubscribe, and send email to the dev@ mailing
list.

]]]

I also recommend to rename "Handy Dandy Issue Tracker Queries" to
"Search Existing Issues" (I like the friendly atmosphere of "Handy
Dandy Issue Tracker Queries" but I'm trying to simplify and reduce
verbosity, even as I propose to add even more new text...)

Finally, I suggest to move the following text:

[[[

You need to have an account to create issues. If you are already a
committer, use your @apache.org account to sign in. Otherwise, you can
apply for an account using the Self-serve Portal. Please add a
reference to the mailing list discussion in the "Tell us a little
[...]" input field to speed up the review process.

]]]

to some appropriate place in Hacking, such as [2], since this only
seems relevant to committers.

(If we decide to extend a Jira account to certain community members,
we can always direct them to [2], though if someone is helpful enough
to justify having their own Jira account, we might consider inviting
them to be committers instead.)

References:
[1] https://subversion.apache.org/reporting-issues.html
[2] https://subversion.apache.org/docs/community-guide/issues.html#issues

Thoughts?

Cheers,
Nathan

Re: Propose changes to the Reporting Issues page

[Stefan Sperling <st...@elego.de>]

On Thu, Jan 30, 2025 at 05:16:51PM -0500, Nathan Hartman wrote:
> Committed to the staging site in r1923465:
> 
> https://subversion-staging.apache.org/reporting-issues.html
> 
> Comments, suggestions, etc., welcome.

I like this, it's a very nice improvement. Much more straightforward
onboarding for people who have never reported a bug before.

Re: Propose changes to the Reporting Issues page

[Nathan Hartman <ha...@gmail.com>]

On Fri, Jan 31, 2025 at 6:08 AM Daniel Sahlberg
<da...@gmail.com> wrote:
>
> Den tors 30 jan. 2025 kl 23:17 skrev Nathan Hartman <ha...@gmail.com>:
>>
>> [...]
>>
>> Committed to the staging site in r1923465:
>>
>> https://subversion-staging.apache.org/reporting-issues.html
>>
>> Comments, suggestions, etc., welcome.
>
>
> Thanks for working on this! I think the /reporting-issues.html page look a lot better now. In particular the yellow box always stood out as a little bit harsch to my eye but now it looks professional.

Thanks to everyone for the feedback!

I've merged this Reporting Issues page redesign to publish in r1923526.

> Regarding searching for issues, we have most discussions on mailing lists and very few items ever land in Jira. The mailing list page has a form which can search in lists.apache.org. Would it make sense to include that form in /reporting-issues.html as well? (It requires a bit of JavaScript to function but it is based on the vanilla-js.com framework so it should be quite easy to integrate).

Sure, that would improve the search for existing issues. I'll look at
the mailing lists page a bit later to see if I can port that search
form to reporting-issues.

Cheers,
Nathan

Re: Propose changes to the Reporting Issues page

[Daniel Sahlberg <da...@gmail.com>]

Den tors 30 jan. 2025 kl 23:17 skrev Nathan Hartman <
hartman.nathan@gmail.com>:

> [...]
>
> Committed to the staging site in r1923465:
>
> https://subversion-staging.apache.org/reporting-issues.html
>
> Comments, suggestions, etc., welcome.
>

Thanks for working on this! I think the /reporting-issues.html page look a
lot better now. In particular the yellow box always stood out as a little
bit harsch to my eye but now it looks professional.

Regarding searching for issues, we have most discussions on mailing lists
and very few items ever land in Jira. The mailing list page has a form
which can search in lists.apache.org. Would it make sense to include that
form in /reporting-issues.html as well? (It requires a bit of JavaScript to
function but it is based on the vanilla-js.com framework so it should be
quite easy to integrate).

Cheers,
Daniel

Re: Propose changes to the Reporting Issues page

[Nathan Hartman <ha...@gmail.com>]

On Tue, Jan 28, 2025 at 1:03 PM C. Michael Pilato <cm...@red-bean.com> wrote:
>
> On Tue, Jan 28, 2025 at 10:51 AM Nathan Hartman <ha...@gmail.com> wrote:
>>
>> >From time to time we get account requests for Jira from members of the
>> community. There is such a request now.
>>
>> Historically we have declined these Jira account requests and directed
>> requesters to discuss their issues at the mailing list first.
>>
>> This wastes everyone's time and efforts, so I would like to improve
>> the Reporting Issues page [1] to hopefully avoid this:
>>
>> I recommend to remove everything until Handy Dandy Issue Tracker
>> Queries and replace it with two new subsections:
>>
>> [[[
>>
>> Report A Bug
>> ============
>>
>> If you believe you have encountered a bug in Subversion, please write
>> to the Subversion Users mailing list (users@subversion.apache.org) and
>> provide at least the following information in your message:
>>
>> * What steps led to the issue.
>>
>> * The expected outcome.
>>
>> * The actual outcome.
>>
>> * The release and/or revision of Subversion. You can copy and paste
>> the output of 'svn --version' or 'svn --version --verbose'. If the
>> issue involves client and server, it may be helpful to provide the
>> versions of both.
>>
>> * If you built Subversion yourself, the compiler and configuration
>> options used.
>>
>> * Any customizations which could be relevant.
>>
>> * Your operating system.
>>
>> * Any other details you believe are relevant. The more detail you can
>> provide, the more likely it is that someone can help. If you can find
>> similar bugs in the issue tracker (see below), please mention those as
>> well.
>>
>> See Mailing Lists (https://subversion.apache.org/mailing-lists.html)
>> for how to subscribe, unsubscribe, and send email to the users@
>> mailing list.
>
>
> Would it be beneficial to provide in this section a copy-and-paste-able template -- similar to what many issue trackers offer -- that contains these very questions?


Thanks for this suggestion. I have re-worked the text to make this a
copy/pastable template among other tweaks...

Committed to the staging site in r1923465:

https://subversion-staging.apache.org/reporting-issues.html

Comments, suggestions, etc., welcome.

Cheers,
Nathan

Re: Propose changes to the Reporting Issues page

["C. Michael Pilato" <cm...@red-bean.com>]

On Tue, Jan 28, 2025 at 10:51 AM Nathan Hartman <ha...@gmail.com>
wrote:

> >From time to time we get account requests for Jira from members of the
> community. There is such a request now.
>
> Historically we have declined these Jira account requests and directed
> requesters to discuss their issues at the mailing list first.
>
> This wastes everyone's time and efforts, so I would like to improve
> the Reporting Issues page [1] to hopefully avoid this:
>
> I recommend to remove everything until Handy Dandy Issue Tracker
> Queries and replace it with two new subsections:
>
> [[[
>
> Report A Bug
> ============
>
> If you believe you have encountered a bug in Subversion, please write
> to the Subversion Users mailing list (users@subversion.apache.org) and
> provide at least the following information in your message:
>
> * What steps led to the issue.
>
> * The expected outcome.
>
> * The actual outcome.
>
> * The release and/or revision of Subversion. You can copy and paste
> the output of 'svn --version' or 'svn --version --verbose'. If the
> issue involves client and server, it may be helpful to provide the
> versions of both.
>
> * If you built Subversion yourself, the compiler and configuration
> options used.
>
> * Any customizations which could be relevant.
>
> * Your operating system.
>
> * Any other details you believe are relevant. The more detail you can
> provide, the more likely it is that someone can help. If you can find
> similar bugs in the issue tracker (see below), please mention those as
> well.
>
> See Mailing Lists (https://subversion.apache.org/mailing-lists.html)
> for how to subscribe, unsubscribe, and send email to the users@
> mailing list.
>

Would it be beneficial to provide in this section a copy-and-paste-able
template -- similar to what many issue trackers offer -- that contains
these very questions?