search

intel / rohd

The Rapid Open Hardware Development (ROHD) framework is a framework for describing and verifying hardware in the Dart programming language.
https://intel.github.io/rohd-website
BSD 3-Clause "New" or "Revised" License
374 stars 67 forks source link

Don't use the GitHub Wiki #305

Closed chykon closed 1 year ago

chykon commented 1 year ago

Motivation

The ROHD Forum currently uses the GitHub Wiki, which has a few downsides:

Desired solution

Ideally, a separate repository could be used for Forum (example), but you can do without it. Here are the suggested options:

The current Wiki can be hidden so that neither users nor developers are exposed to outdated information. You will also need to update all links.

In addition to the ROHD Forum, the Wiki has information added by @quekyj. As far as I understand, this data also follows along with changes related to the site and tutorials, so it does not need to be transferred anywhere, and the Wiki can be safely hidden. Correct me if I'm wrong.

Alternatives considered

No response

Additional details

No response

mkorbel1 commented 1 year ago

Thanks for the thought and insight! You raise some good points.

What do you think of making the new repo that we were going to use for the website a more broad repo that could include the website, meeting minutes, and other miscellaneous documentation stuff in the future not directly appropriate for the main repository? I don't know what it would be called though, and maybe that's just a lazy solution? Hosting it on the website doesn't seem too inappropriate?

I'm a bit reluctant to spam the main repository's commit history with minutes and agendas.

The discussions idea is possibly good, but I'm unsure how to keep it well organized/categorized in there. Do you mean just one discussion with a new comment added each meeting?

chykon commented 1 year ago

What do you think of making the new repo that we were going to use for the website a more broad repo that could include the website, meeting minutes, and other miscellaneous documentation stuff in the future not directly appropriate for the main repository?

This is a good idea. The new repository can be seen as a mono-repository for "non-main" sub-projects in the ROHD umbrella project.

I don't know what it would be called though, and maybe that's just a lazy solution? Hosting it on the website doesn't seem too inappropriate?

How to call - it is necessary to think. We need something abstract. My suggestions:

I think this is a good way to avoid the bureaucracy (which you pointed out) associated with creating a new repository. A mono-repository may be more difficult to maintain, but maintaining many small repositories can also be difficult.

The discussions idea is possibly good, but I'm unsure how to keep it well organized/categorized in there. Do you mean just one discussion with a new comment added each meeting?

Yes. I think it might look like this:

  1. Create a new discussion ROHD Forum (zero message describes what it is, how to join)
  2. A message is created that indicates the date and time of the event, topics for discussion
  3. We are waiting for the end of the meeting
  4. We supplement the message with a brief summary of the meeting
  5. GOTO 2

If the idea of a mono-repository is accepted, then it can be placed there.

mkorbel1 commented 1 year ago

Referencing #221 here since it's related.

I'm looking at flutter and dart for inspiration, and they both have many repos under their organization umbrella: https://github.com/flutter https://github.com/dart-lang

They also both have a website repository, though they name things differently: https://github.com/flutter/website https://github.com/dart-lang/site-www

They both use git submodules for shared content, in this case they both use some of the same shared content: https://github.com/dart-lang/site-shared

Since the wiki and minutes contents still feel like content that could be reasonably hosted on a "website" or "landing page" for the whole ROHD ecosystem, I'm thinking naming it along those lines would be fair. While names like monorohd or rohd-misc are more generic, they seem almost too generic, to the point where people might think it's a random utility repo.

Some names that sound reasonable to me are:

I think I'm leaning towards rohd-website since it's immediately very clear what it is.

@quekyj made a good point that using the word "website" (or similar) in the name of the repo, then hosting the website there, makes the URL look a little silly: "https://intel.github.io/rohd-website/". It is redundant to say the website URL has the word "website" in it. I figure we can just forward from "https://intel.github.io/rohd/" to the website version, so links won't need to include it.

mkorbel1 commented 1 year ago

I think using submodules that point to ROHD, ROHD-VF, ROHD-Cosim, and any others that pop up could be a reasonable way to handle references to content in each of the repos. However, that would mean each time we commit or release a version, we'd also need to go manually update the website.

An alternative could be some sort of cronjob that regenerates the static page based on latest main contents on each of the other projects.

Once the new repo is created, I guess we can experiment with different ways to manage this.

quekyj commented 1 year ago

I think I will remove all the information inside Wiki once the bootcamp is complete. Btw, I am thinking that adding a FAQ section will be helpful as well.

mkorbel1 commented 1 year ago

The repo has been created here: https://github.com/intel/rohd-website

mkorbel1 commented 1 year ago

The contents on the wiki, including the forum, have fully migrated to the ROHD website! https://intel.github.io/rohd-website/