Rationale for a top-level meta-repository #114

Closed ghost closed 4 years ago

The problem

The FOSSRIT GitHub organization is difficult to navigate, including as it does--at the time of this writing--194 repositories going back more than 6 years, having been created, used, or maintained--and in many cases, abandoned--by several generations of participants. This can be particularly difficult for newcomers browsing the organization and not accustomed to using GitHub search features nor aware of keywords to use relevant to the organization. The default repository listing sorts by most-recently active at the top and buries key but only periodically-updated repositories in the middle of the pack.

There are also a number of difficulties for more-experienced participants.

The criteria for including a repository in the organization is poorly defined.
Some repositories are native to the organization, but some are forks. If and how to bring a repository or fork into the organization is not well defined.
What's more, whether to keep a repository in the organization is not well defined.

Proposed solution

A meta-repository like this one FOSSRIT/fossrit :smile:

This is similar to, but more flexible and more expansive than, the pinned repositories feature.

This approach of having one navigational meta-repository is used by a number of other GitHub organizations. A prominent one that most easily comes to mind is that of Travis-CI but there are others.

The list of top-level directory objects will be kept short so that the README is not too far down the main repository page. The README, then, will be maintained as an easy-to-browse single page for navigational information, with links both to key GitHub-hosted FOSSRIT repositories as well as to web and community resources found elsewhere. The preferred form for links in documents hosted elsewhere pointing to this organization should be https://github.com/FOSSRIT/fossrit while deprecating ~~https://github.com/FOSSRIT/~~ .

The issues and, possibly, wiki associated with this primary FOSSRIT/fossrit meta repository can serve as unambiguous first stops for any journey into the organization. Any query, discussion topic, or document can find a home here, first, if no other location is immediately apparent. Discussions or document need not remain in this top-level repository and can be moved to or continued in more specific repositories later.

Any discussions starting at this meta level, but which discussion is relevant to the organization as a whole regarding policies and procedures can remain. Issues originating in other repositories that turn out to have a wider, organization-wide aspect can be moved to or continued in this top-level repository.

This repository would either become one of the pinned repositories or, perhaps better to funnel participation through it, would be the only pinned repository.

Alternatives

Maintaining more of our documentation and navigational aids within the vast suite of institutionally-maintained and promoted software-as-a-service is one clear alternative: Learning management systems, student organization systems, internal-only repository hosting, institutional wikis, etc. To those less invested in FOSS collaboration methodologies these may seem like the best, obvious choice.

However, these are generally not so portable beyond the institution that hosts them and represent even worse lock-in than GitHub does, and moves the documentation for our code hosting away from the code hosting itself.

Going in the other direction, perhaps we should set up our primary entry-funnel meta-repository at a repository hosting site whose server software is itself FOSS: Pagure, GitLab, Gogs/Gitea/notabug, Framagit, etc.

It might seem that the effort to maintain a less participatory, top-level web site like a Wordpress instance or the fossrit.github.io page obviates the need for something like this. However, these serve the needs of the community more broadly, rather than those of the code-hosting and development aspects in particular: For most of the community, they remain a read-only medium, with a narrow channel for onboarding maintainers and contributors.

Also, as we've seen in recent years, maintenance of such infrastructure carries its own challenges idiosyncratic to the software used and the way each is hosted which require effort to learn and maintain. When they are working, they are, in a sense, complementary to a code-hosting organization meta-repository: Each clearly should contain links to the other, but they do not substitute one for the other.

Additional context

It will be important to keep what shows up on the main page of the repository fairly clean and navigable. It might become lengthy, but if we do reasonably well in categorizing and prioritizing the page layout in "inverted pyramid" form, keeping the most relevant information at the top of the README, it will serve us well.

Deeper into the document tree we can put other organization-wide documents like polices, procedures, HOWTOs, etc.

Pages further down may be included which incorporate alternate views into the repository, including embedded links to searches, eg

hfoss
(minor)[https://github.com/FOSSRIT?q=minor]
POSSE
monroe
election

These can serve directly to aid navigation through browsing, but can also serve as models for the use of the search features and of keywords particularly useful within the organization. Many features of these documents will largely be portable, useful beyond GitHub and any GitHub-specific organizational features like tags.

Special-purpose managerial meta-repositories like:

probably wouldn't be replaced by this FOSSRIT/fossrit meta-repository. We would link to them from it. There might be some duplication between it and them, but with judicious use of crosslinks amongst them all that might turn out OK, or even well.

@ritjoe Based on my understanding of quickly reading this, are you thinking of an awesome-fossrit-style setup?

I propose we drive these changes and centralization through the fossrit.github.io website.

On Thu, Nov 29, 2018 at 03:14:34PM -0800, Justin W. Flory wrote:

I propose we drive these changes and centralization through the fossrit.github.io website.

How do you propose to avoid confusion as to whether an issue filed against fossrit.github.io is a technical issue specifically with the content or operation of that particular web site, versus it being a top-level organizational issue file by a newcomer to the project who doesn't know which of our hundreds of repos in might better belong in?

a top-level organizational issue file by a newcomer to the project who doesn't know which of our hundreds of repos in might better belong in?

@deejoe I prefer to raise the visibility of FOSSRIT/tasks, since organizational discussion is already happening there today. I have bandwidth to drive this change through fossrit.github.io and the tasks repository, but it feels irresponsible of me to lead creation and maintenance of a top-level repository in addition to what I am already maintaining. It duplicates my existing efforts and I risk forgetting about it if I'm not actively looking at it (like I did when I scrolled past this repo and remembered this issue is still open).

@deejoe @jwflory I think we should discuss this during FOSS Hours on Tuesday. I sort of have an idea how to get the best of both, but I think we need to have the meta-talk on how this will work again.

I'm going to jump back to this and begin opening issues and putting things together in the way I had in mind for this repo. Instead pushing this into the FOSSRIT github organization I'll do it through my own account. If what I'm doing and the way I'm doing it there gains any support for bringing that over to the FOSSRIT organization then we can try to make that happen later.

See https://github.com/ritjoe/fossrit

Picking up at https://github.com/ritjoe/fossrit/issues/1

Wow, I have no idea why, but Github just sent me another copy of the opening email from this issue.

I'm going to close this and re-open if/when I get anything to the point I feel like bringing back over. In the meantime, see https://github.com/ritjoe/fossrit I guess.

FOSSRIT / tasks

Rationale for a top-level meta-repository #114