GitHub: Simplify root directory and migrate documentation

[Lamparter]

I'm an enthusiastic user of IronPython and have been for years... it's sad to see the last commit to main being nearly six months ago!
In this PR I've taken the effort to simplify the root directory and make some other few contributions in an effort to hopefully revive the work on this project to that of a big, ambitious project that IronPython is.

[Lamparter]

@slozier would you mind reviewing this PR when you get a moment?

[slozier]

Thanks for the PR! Seeing community PRs definitely helps motivate me to work on the project.

I'm not sure how I feel about using the wiki for documentation. The biggest drawbacks for me would be:

• The content is not visible in the cloned repo so I tend to neglect it. For example if I want to drop support for .NET 6 (which is no longer supported by Microsoft) I usually search though files to find relevant things to change.
• Can't keep different branches of documentation, for example main and 3.6 could have different Package Compatibility or What's New pages. Although it looks like in practice I haven't done that.

@BCSharp I know you played with the documentation a bit. Any thoughts or concerns?

[slozier]

Although I like the idea of better structured bug reports I'm not sure this set of templates is well suited for the project. I assume this lets you pick a style before proceeding to filing an issue? Is there an escape hatch that allows not using a template?

[Lamparter]

There is a way to still use blank issues, it can be enabled from the config.yml file I created. I'll enable it now.

[slozier]

Seems generally fine. Will probably need to adjust the issue templates some more but it's a good start.

Looks like renaming LICENSE might have broken the packaging step.

[slozier]

Oh hmm, perhaps we should not be renaming the LICENSE file. The license notice at the top of every file says:

See the LICENSE file in the project root for more information.

[Lamparter]

The NuGet package built-in README will need to be changed as well, since NuGet isn't using the latest of MarkDig and doesn't support more recent GitHub Markdown like info bars.

[slozier]

The NuGet package built-in README will need to be changed as well, since NuGet isn't using the latest of MarkDig and doesn't support more recent GitHub Markdown like info bars.

What's wrong with the NuGet package README? I guess some of the URLs will have to change, but I don't think it needs substantial changes.

[BCSharp]

@Lamparter, I am enthusiastic to see an enthusiastic contributor!

I'm not sure how I feel about using the wiki for documentation. The biggest drawbacks for me would be:

• The content is not visible in the cloned repo so I tend to neglect it. For example if I want to drop support for .NET 6 (which is no longer supported by Microsoft) I usually search though files to find relevant things to change.

• Can't keep different branches of documentation, for example main and 3.6 could have different Package Compatibility or What's New pages. Although it looks like in practice I haven't done that.

@BCSharp I know you played with the documentation a bit. Any thoughts or concerns?

I am very positive about moving the documentation to the GitHub wiki. Actually, I was planning to do it myself at some point, but never got to finish it. Over the years, I would clean up the old wiki (moving any useful info to the checked in docs), hoping for one day to put it to good use. Writing .md docs was an interim solution. It was easy for me since I have write access to the repo, but a regular would-be contributor had to go through the whole PR-submit process, just to fix a typo. Yes, some did it anyway, but I feel we would have gotten bigger engagement with the wiki. I think that even I would have been more inclined to make small fixes more often.

However, @slozier, I share your concerns about the move; here is how I see them:

• I, too, use search through files to make sure that some changes are properly accounted for. I usually use VSCode for this purpose, its search/replace seems to offer much more pleasant experience than the heavyweight VS (I prefer the latter for debugging though). Luckily, the wiki is a git repo too, so in VSCode it is simple to create a workspace spanning two cloned git projects, checked out side by side. Any global search scans then both repos, as if they were one. Also, VS is not available on Linux, and (since recently) not on macOS, so expect to use VSCode more and more often. I don't know your preferred toolset, but if you do not use VSCode, you may want to give it a try. I also think (though never tried so might be wrong) that it is possible to configure VS to have a solution that included the wiki pages next to the regular IronPython code.
• About "Package Compatibility": I'd expect that in general, the wiki documentation pertains to the current main, which currently is 3.4, and when there is some discrepancy between 3.4 and 3.6, it is explicitly tagged on the page. For package compatibility, it could even be separate wiki pages. For maintainability, version-specific comments could be tagged in some standard way so again, the search can pick them up. In code I use string Python 3.6 (or any other version that the code implements), but I search on 3.6. Another point: having "Package Compatibility" in the wiki will invite reports from the field about packages that work that we may have never tried ourselves.
• That said, some documents do not tend themselves to be included in the wiki. Of the top of my head it is the feature sets and the "What's New" series. Especially in the case of "What's New", changes are version-controlled together with the corresponding code changes, so it is (relatively) easy to find out how a specific piece of functionality was implemented and when. Even if there is some discrepancy in commits, that is, a feature had been completed and only later the checkmark added to "What's New" (we are not perfect, are we 😃), the PR with the commit with the change to "What's New" would often refer to the other PR that implemented the feature (at least, that's how I have done that), so there is an audit trail. Similarly, with an earlier checkout one can find the corresponding state on feature implementation by simply looking at the "What's New" documents. Further, changes to "What's New" documentation do not benefit from the lightweight approach of the wiki; they should be updated only after careful consideration.

[Lamparter]

What's wrong with the NuGet package README? I guess some of the URLs will have to change, but I don't think it needs substantial changes.

It will break on NuGet

[Lamparter]

I was also working on a little secret something, perhaps that might be useful here 😁

That is, of course, a new website!

[slozier]

Alright, what's the plan with this one? I'm fine with moving docs to the wiki as well as the github issue templates. I'd like to keep the "what's new" files in the repo as I consider them more like developer checklists than documentation.

[Lamparter]

Where do you want them to go? The Documentation folder?

[slozier]

Thought this removed everything from Documentation? Can't think of a good spot though so wherever works for you.

[Lamparter]

I think .github might need to be the place to put this if you don't want them in the wiki.
Though perhaps it might be good to add it as src\spec or src\todo?

[BCSharp]

Though perhaps it might be good to add it as src\spec or src\todo?

I'm fine with either one. Probably leaning towards spec, since our TODO is way longer (e.g. includes the whole Issues list).
I wholeheartedly support taking them out of the project front page/root dir, but .github seems to me a little bit too obscure (after all, it is a dot-directory). I assume you will link to them from the Wiki, once this PR is merged?

@slozier , are you OK with Features out of the repo?

[slozier]

@slozier , are you OK with Features out of the repo?

The feature symbols you mean? They're more of a dev reference and not something a user would care about. Would fit in with src\spec I guess.

[Lamparter]

They might be easier to edit and reference if they were in the wiki.