search

solid / solid-spec

Solid specification draft 0.7.0
Creative Commons Zero v1.0 Universal
1.13k stars 103 forks source link

Proposal: add issue templates to this repo #227

Open melvincarvalho opened 4 years ago

melvincarvalho commented 4 years ago

In github it is possible to create issue templates in order to guide a user in how to express an issue

There was concern expressed about confusion caused when raising spec related issues

Creating issue templates could have the effect of killing two birds with one stone

I propose that we begin with the standard two types of issue templates

Add templates

The text then becomes part of the repository. And it would be possible to iterate on that text.

csarven commented 4 years ago

Feature requests is out of scope of 0.7. They belong in the solid/specification repository.

New issues can only be about erratas to the 0.7 spec.

melvincarvalho commented 4 years ago

@csarven thanks for the input

The idea of feature requests would be to guide the user in where to post

Another way would be only to have a bug report item with an explanatory message:

One looks like this:

image

The other looks like this:

image

You can imagine that boiler plate text to be something useful to guide the user and lower confusion

Supportive of guiding users NOT to raise feature requests, using either path

dmitrizagidulin commented 4 years ago

-1 to this. This repository is archived. There is no need for issue templates for it.

kidehen commented 4 years ago

In github it is possible to create issue templates in order to guide a user in how to express an issue

There was concern expressed about confusion caused when raising spec related issues

Creating issue templates could have the effect of killing two birds with one stone

  • Improving the quality and nature of issues raised here (which in isolation would be a good thing)
  • Ability to guide users more effectively going forward

I propose that we begin with the standard two types of issue templates

  • bug reports
  • feature requests

Add templates

The text then becomes part of the repository. And it would be possible to iterate on that text.

How about dropping the "Feature Request" option so that whoever encounters the form ends up performing either of the following actions:

  1. Logs a fix or correction to the draft repo
  2. Seeks an alternative repo (i.e., specifications overseen by @csarven) for new features related matters.

The suggestion above should solve the problem that's underlying this thread. IMHO.

dmitrizagidulin commented 4 years ago

@kidehen

The suggestion above should solve the problem that's underlying this thread. IMHO.

The problem underlying this thread is - this repository is no longer active. It does not need an issue template, since no new issues will be created.

akuckartz commented 4 years ago

@melvincarvalho If the other stakeholders will agree with this very likely depends on the text of the templates.

kidehen commented 4 years ago

@kidehen

The suggestion above should solve the problem that's underlying this thread. IMHO.

The problem underlying this thread is - this repository is no longer active. It does not need an issue template, since no new issues will be created.

That worldview is the basis for the objection raised by @melvincarvalho.

We have conflicting world-views here and the goal is to solve this issue harmoniously for the betterment of the broader community.

Again, I am calling to flexibility here with a fundamental understanding that individuality and community can be strange bedfellows, especially with the behavior of an app (like what's provided by Github) in the mix.

kidehen commented 4 years ago

Feature requests is out of scope of 0.7. They belong in the solid/specification repository.

New issues can only be about erratas to the 0.7 spec.

Okay, and I believe that's consistent with the template modifications I suggested earlier to @melvincarvalho .

dmitrizagidulin commented 4 years ago

@kidehen

Again, I am calling to flexibility here with a fundamental understanding that individuality and community can be strange bedfellows, especially with the behavior of an app (like what's provided by Github) in the mix.

The impression that I'm (likely erroneously) getting, is that this discussion is proposing is to fork the Solid project and community.

This by itself is totally fine. Forking is a time-honored tool, and is important to free software in general.

What is not fine, is to create this fork at the expense of causing confusion for Solid developers, which is what not explicitly archiving this solid-spec repo would result in.

kidehen commented 4 years ago

Let's be very clear here. What you and @melvincarvalho are proposing is to fork the Solid project and community.

This by itself is totally fine. Forking is a time-honored tool, and is important to free software in general.

What is not fine, is to create this fork at the expense of causing confusion for Solid developers, which is what not explicitly archiving this solid-spec repo would result in.

I want to be crystal clear with you.

My involvement in this thread is strictly about contributing what I can to calm things down by urging flexibility and mutual understanding across differing views.

Once again, I am simply calling on the "Wisdom of Solomon" to be applied for the greater good.

I hope I have made myself intentions clearer, if prior attempts haven't achieved that fundamental goal.

dmitrizagidulin commented 4 years ago

@kidehen ah, thank you, my apologies. I do appreciate you wanting to calm the discussion. Sorry bout that.

kidehen commented 4 years ago

Feature requests is out of scope of 0.7. They belong in the solid/specification repository.

New issues can only be about erratas to the 0.7 spec.

Yes, and we can achieve that via the tweak suggested in my response :)

Issues associated with 0.7 are fundamentally of type: errata i.e., no "new features" goal is achieved by not including any "new feature" option in the template that @melvincarvalho is putting together.

akuckartz commented 4 years ago

no "new features" goal is achieved by not including any "new feature" option in the template that @melvincarvalho is putting together.

One alternatively could provide a pseudo "new feature" option with a template text like:

"Do not suggest new features in this repository. Do that in the other repository nearby. Please see our README for an explanation."

kidehen commented 4 years ago

no "new features" goal is achieved by not including any "new feature" option in the template that @melvincarvalho is putting together.

One alternatively could provide a pseudo "new feature" option with a template text like:

"Do not suggest new features in this repository. Do that in the other repository nearby. Please see our README for an explanation."

Yes, but leaving out "new features" all together in the template helps to avert confusion that will inevitably arise if "new feature" appears as an option or pseudo-option etc..

akuckartz commented 4 years ago

@kidehen Yes, but if someone is already looking for a way to submit a feature request he or she will perhaps simply submit a "bug" instead.

Anyway, I think the README is what matters even more.

melvincarvalho commented 4 years ago

@dmitrizagidulin thanks for your input. I really would like to try hard to listen to and address your concerns. You can reach out to me off chain if you want a fuller explanation.

If I may provide some context. Looking at the open issues on this repo, there are 4 since August. 2 of them are from timbl and 1 from Ruben. The other issue is a query that was answered and that could well be closed now.

So that's approximately 4 open issues in 9 months. The other specification repo has 148 issues open, and has been going under a year. That's 4 vs 148. Not trying to minimize the issue here, I want to help solve it, but we are already doing quite well, and we can just do a little bit better I think and satisfy everyone.

You yourself have done quite a bit of work on this repo, so you will know that edge cases come up and it's useful to keep a track of them. Wouldnt it be nice if we could mark 0.7 as bug free and have it as standard for Gold and LDPHP to get to?

I hope I can convince you that nothing nefarious is going on here, and if you feel there are deeper issues unaddressed, please feel free to reach out to me.

melvincarvalho commented 4 years ago

@akuckartz @kidehen hear you both. I'll do a template for the simpler version (without 'feature request') for now and think up some appropriate text. As you say, that text will be clarifying.

The README can be changed as appropriate, and thanks for raising that separate issue

https://github.com/solid/solid-spec/issues/228

kidehen commented 4 years ago

@kidehen Yes, but if someone is already looking for a way to submit a feature request he or she will perhaps simply submit a "bug" instead.

Anyway, I think the README is what matters even more.

Yes, the README should act as an additional layer of communication to prevent confusion etc..

melvincarvalho commented 4 years ago

How about this text?

Issues raised are for bug fixes only. For proposals and feature requests please see README

image

Open to changes in the copy

melvincarvalho commented 4 years ago

I have created a PR for the above, which I hope might address at least some of the concerns outlined. This was originally suggested independently by Ruben here, noting the conversation did evolve later

It is designed to be self contained and modular. And direct users to only post bug fixes / errata up to 0.7 in this repo, and hopefully partially addresses this comment from Sarven

The boilerplate is fairly standard and contained in the PR. I would be happy to change it

I would like to acknowledge that while this might not address every concern, it may be helpful, to make some progress

The text in the README can evolve in a separate PR, and should take into account timbl's comment

For the record I will not object to any text suggested to the README, as I think it's only helpful to object to one thing at a time :)

The sole concern is to prevent the early archiving of this repo, at this time, for the reasons outlined