Differentiate "non project" repos

[HoverBaum]

This project is totally what I was looking for to finally organize where all my repos are at right now. Though I stumbled over a few repos while going through all of mine and adding statuses.

1. Repos that are for bug reports. I have a few repos that simply illustrate minimum cases to recreate a bug of a framework I was using.
2. Presentations. Other repos are RevealJS based presentations that are mainly there to have the presentation available using the gh-pages branch.
3. Experiments. They are in a sense in the "Concept" status but are never meant to reach production.

For all of these I feel like the current statuses don't really describe where they are at. Mainly because they are not traditional coding projects that aim for a release and production version.

So I would like to discuss the suggestions of adding something along the lines of experiment or finished.

The first indicating that a repo is never meant for production though being a project in the traditional sense. A real world example: my department head had me build a OPA Framework to get to know the basics.

Finished could be used for things like presentations. While they are in a sense Inactive I feel like that doesn't convey the actual status of the repo but merely forces it into the current constraints of available statuses.

[jantman]

@HoverBaum Once again, many apologies. I had some issues with GitHub notifications a while back, and I've been embarrassingly bad at actively checking for open issues and PRs.

I certainly understand the problem, and honestly I hadn't thought about use for non-code projects. I have a few repos that are for bug reports and experiments... personally, I've been using Abandoned for the bug report repos, and either Abandoned or Unsupported for experiments depending on the state they're in (essentially Unsupported if the experiment is a working example, Abandoned if it's not). But I'd be open to handling these cases more explicitly.

I've been hesitant to add any more statuses... do you have any thoughts on expanding the definitions of some of the existing ones to explicitly include non-code repos?

[HoverBaum]

I also didn't think about the topic much after initially labeling all my repos.

This idea comes from thinking about what repostatus really tells one about a repo and that I think is the phase of development in which a repo is. So repo status tells us where a project is in terms of being developed. Let me illustrate that some more in terms of what I think states stand for and how they are related.

This state diagram should illustrate my thoughts some more. I see "Concept" as the first phase for any project. As such simple experiments could be just that, a concept.

Then the status of a repo is divided into two groups of statuses based on the repo having ever reached a stable version or not. With "WIP" being the state from which to move from the first to the second group.

Unstable repos After being a concept a repo should either stay that way or become WIP because only than can it be "Abandoned" or "Suspended". It should also only move back to WIP and never Concept again.

Stable repos Here changing from any one to any other state is feasible because the state only talks about how the stable version is handled.

With these thoughts about what the repo statuses stand for and represent let me address my initial points again.

3 Experiments

For 3 I feel like experiments could very well be handled by expanding the definition of "Concept". Maybe it could stand for:

Minimal or no implementation has been done yet or an idea is just being tried.

According to my model from above this would perfectly fit those cases.

1 Bug repos

Here I feel like they are not really a project but in a way they have reached a stable state because the goal of them (showcasing a bug) has been achieved. Thus I feel the would fall into stable repos and would most likely be "Inactive" or "Unsupported"

Maybe it would be good to expand "Unsupported" to include that the repo might have served it's purpose already.

2 non code repos like presentations

Looking at this with the understanding that repostatus talks about the progress in development and how far it has come I feel like they would probably all be "Inactive".

I feel like some of my original thoughts were based on a not so precise idea of what repostatus is talking about in regards to my repositories. Maybe what I was really looking for is a way to provide even more semantic information about my repository. But maybe GitHubs "topics" fill that role perfectly. I could see them being used to add the information that this is not a code project repository but a collection of information or a presentation.

Further thoughts

The way I now think about what repostatus represents I feel that the aspects of "Inactive" and "Unsupported" which talk about how support is being provided feel like they might not really belong to the repostatus. But I would love to hear from you about this.

Maybe a more sophisticated graphic about repostatuses could be included on the website to help people think about which status is right for there repository along with some more examples.

[jantman]

@HoverBaum That was an utterly amazing, detailed, well-written post. I agree with almost everything you said, and I think you said a lot of it more clearly than I have. If you'd like to cut a pull request against the website to include some of this (either the graphic you used or another version of it, or some of this explanation as well), either on the index page or on a separate "logic" or "Concept" page, I wouldn't be opposed to that at all.

Or do you think that perhaps - since I really wanted this to be a living project that incorporates the views of everyone who uses it - I should create a Discussion or FAQ or Examples page on the Wiki and make it easier for community involvement?

I agree completely with your point that this is really about phase of development, and your diagram works really well in my mind, though I don't think I ever took the time to think about the transitions and diagram them all out. I also agree with you on points 1 and 3, Bug Reports and Experiments. I agree about 2, Non Code Repos, as well... I don't have many of them, and I think the ones I have, I probably haven't even put repostatus on. But yeah, I think my gut reaction would be to probably call most of them "Inactive" (or some other status if it fits better) and rely on something else for semantic information/metadata.

I have mixed feelings about GitHub Topics... I think they're cool and useful for adding semantic information and filtering/searching/browsing projects. But at the same time, while GitHub has become pretty ubiquitous, there are still a handful of projects on other git servers... whether GitLab or project-run servers (like many of the big F/OSS umbrella projects), or non-Git SCMs... and the F/OSS lover in me really likes this being an open standard that's not tied to any one SCM or hosting provider.

I understand how you're thinking with the Inactive/Unsupported possibly being separate from the actual status, and I suppose that on a technical, semantic level I agree with you. However as I mentioned in the blog post that started all this, my guiding goal was really to answer the questions that I often have when I come by a project on GitHub:

• How complete is this? Should I expect it to be "stable" software, mostly working, or not really useful at all?
• Should I expect active development and support, maybe some bug fixes, or nothing at all?

I'm happy maintaining this project, but I really don't want to be the person who makes decisions... I think that should be a community effort.

[jantman]

PS - a GitHub search for code containing "http://www.repostatus.org/badges/" excluding my own repos yields 1,265 results. I really want community involvement in any non-trivial decisions...

[HoverBaum]

@jantman I am definitely in favor of having a community involvement though I am not experienced with this sort of thing ^^

I feel that it’s the minimum set required to describe a project along the two axes which I consider important: usability (is the code here complete enough to “work” for something) and support/development status (is it being worked on, or are there plans to do so in the future).

That but the entire thing into perspective for me nicely. And I do think that adding more of an explanation to the website would greatly help us discuss about the future of this project as well as help other to use it. I will gladly put up a pull request as a base of discussion for this some time during the week. That should be a good place to discuss if this is the direction repostatus should move towards.

wiki / FAQ

A place to collect examples of decisions could be of great help. And FAQ should be something that compiles over time should there be FAQs. But this is a point where maybe someone with more experience for longer lived community projects could voice an opinion.

Statuses description

As we keep saying this should have a greater community involvement. For that purpose I opened #22 With our discussion so far I can totally see the purpose and need for "Inactive" and "Unsupported". Though more of an explanation that this is what repostatus aims to talk about would really help (pr incoming).

About higher involvement of more people: I am not really sure if issues and therefor GitHub in general are the best place for that because people basically don't really look at things other than their own issues. Maybe something like slack or gitter would be nice? Though longer posts in issues are better for cross timeline cooperation.

[jantman]

Thanks to all for the input. Since it's the weekend I'm going to let this sit for another day or two in case anyone else wants to offer input, but I'll come back to it this coming week.

As to slack/gitter, I agree they're good, but I don't expect many people to be so involved in this project that they'd stay in a slack or gitter channel...

[ScottPJones]

This seems to miss one status, that of "superceded". For example, among the Julia packages, there was a "ICU.jl", which wasn't being maintained at the time, I made a fork and maintained it there, and eventually, my fork both got moved into an org I started from my personal github account, and then that one ended up getting superceded by a "StrICU.jl" package (with a new API).

One other problem I see though, is that if a repo is moribund and the owner is not merging any PRs (as happened to me with the original "ICU.jl"), how are you going to get them to merge a PR so that their README.md has an "Inactive" badge?

[jantman]

Wow, I guess I've let this one sit more than "a week".

@ScottPJones

So... regarding your second comment, this isn't a solution to the problem of maintainers that throw away their computers, join an Antarctic expedition, or otherwise stop accepting PRs. Short of piling up Issues and PRs, I don't think there's a real solution to that problem on GitHub. This project aims to help maintainers who at least make a commitment to keeping the status updated (personally, I go through all my repos a few times a year and make sure the status is accurate).

Regarding "superceded", I'd say that falls under the "moved" status:

The project has been moved to a new location, and the version at that location should be considered authoritative. This status should be accompanied by a new URL.

Perhaps the wording on that could be fixed up a bit, but the intent of it is "go to this other URL to get this code", which I'd say would also be used in the case of superseded projects, forks that become authoritative, etc.

[ScottPJones]

So... regarding your second comment, this isn't a solution to the problem of maintainers that throw away their computers, join an Antarctic expedition, or otherwise stop accepting PRs.

I was thinking that for things like curated lists of packages could use these.

Moved is fine for what happened with ICU, but with ICU -> StrICU, there's an overlap, both work on v0.6 of Julia, but only StrICU works after that, or with the Strs.jl package. That's what I meant by superceded - something that is still maintained for old versions, but moved / replaced for later versions.

[waldyrious]

Could the term "replaced" be sufficient to cover both the "moved" and the "superseded" cases? I realize it's not as precise, but there's some value in keeping the list of possible states short and memorable.

[jantman]

I'm really not sure what to say on this discussion, so this is one of the cases where I'll just defer to the other users of this project... if I can get a few comments agreeing on what should be done, that's what I'll do...

[ScottPJones]

@waldyrious, replaced might be good enough :+1:

[HoverBaum]

I would consider my initial issue as closed with the merge of #25 .

@ScottPJones @waldyrious if you feel that repostatus needs a new state or to rename an existing one I think it will be better to track that on a dedicated issue :)

[waldyrious]

@HoverBaum agreed, it makes sense to track it separately. I just opened #26 for that purpose.