Serving from 'docs/' Folder to Include Site Sources

[tajmone]

I noticed that you're serving the GHPages directly from the repo root.

You might consider to switch to using the docs/ folder instead, which would allow the rest of the repository to contain the PML source files, assets, etc. to build the static HTML website, instead.

While this wouldn't affect how the online website is viewed, it would allow users to contribute to it by submitting changes to the PML sources, or other assets. E.g. the repository could contain Sass sources to generate the stylesheets, and use Rake to manage building the website, its assets and any required tests and validation.

The PML source repositories for the various docs (specs, examples, articles, etc.) could be integrate via Git submodules, which would make working with website sources a very smooth experience.

You'd still have the same static HTML contents the docs/ folder, but with the benefits of having all the source files in the same repository.

[pdml-lang]

You might consider to switch to using the docs/ folder

Done. Thanks for the tip.

[pdml-lang]

The pdml-lang.github.io repository now contains all source files, as well as instructions to build the PDML website.

I decided to not use Git submodules, because it is easier to maintain the website if everything is stored in one repo.

I now plan to:

1. Transfer all issues and discussions from the basic-specification repo to the pdml-lang.github.io repo. Other existing repos related to PDML documentation don't have issues or discussion entries.

2. Remove all existing repos related to PDML documentation, because their content is now stored in pdml-lang.github.io.

Is there a better way to keep the issues and discussions?

I intend to do the same changes in the PML repos.

[tajmone]

The pdml-lang.github.io repository now contains all source files, as well as instructions to build the PDML website.

Cool. I haven't yet had a chance to test the creator/ tool, but I can see that since it's in Java the good thing is that there are no extra dependencies involved.

I decided to not use Git submodules, because it is easier to maintain the website if everything is stored in one repo.

Overall, I'm not against Git submodules.

It's true, they add some annoyance and extra work since they need to be properly initialized and their pointer has to be constantly updated (all operations which contributed to submodules' bad fame) and you ultimately have to create commits across multiple repositories — which can be particularly tedious for contributors, since a given changeset involving changes to both the host repository and its submdodules results in multiple (and unsynchronized) PRs spread across different repositories.

But despite all these downsides, they provide the benefit of allowing each subproject to be kept isolated, which allows more freedom to third parties who might want to include them into their own projects, individually (e.g. for translations, transpiling to other formats, or other use cases).

Having said that, in the current situation it probably makes more sense to keep things simple and store all the material under a single umbrella repository. If in the future a real need arises to justify sub-moduling the sources to facilitate other projects, you can always do it by simply copying the contents of any given subfolder to a new repository (and probably Git also allows to extract such folder without loosing its entire commits history, via some advanced options).

I now plan to:

1. Transfer all issues and discussions from the basic-specification repo to the pdml-lang.github.io repo. Other existing repos related to PDML documentation don't have issues or discussion entries.

Makes sense. Should also be fairly straightforward.

2. Remove all existing repos related to PDML documentation, because their content is now stored in pdml-lang.github.io.

If you delete a repository you can still recreate it in the future, unlike renaming which permanently prevents you from reusing the original name, which becomes "hostage" of the redirection mechanism.

Is there a better way to keep the issues and discussions?

I believe there is: by enabling the new Dashboard features and migrating each project from "classic" to "new" interface:

Migrating from projects (classic)

Although I believe that the new Dashboard is no longer Beta, the switch is not automatic since it changes the UI and workflow, and therefore old users who started with the old Dashboard have to manually migrate to it (on a per-repository base, or at once for all projects).

You can access the Beta features from your GH User menu (click on your avatar, on the top-right corner to reveal the menu) and then choose "Feature preview".

The new Dashboard and Projects (which was announced over a year ago IRC, and which we briefly mentioned elsewhere) has been greatly improved since it allows you to interconnect all your repositories and manage them from a centralized control panel, i.e. tracking Issues per topic across your entire organization.

It even works better when your account has multiple Organizations (e.g. PML and PDML, as independent orgs) and has Teams — but unfortunately all your repositories are stored under a User account, not an Organization, so you can't benefit from Teams and all the extra collaborative features and settings that come with it (even in free edition), so it's too late for that.

But even as an individual User account you can greatly benefit from switching to the new Dashboard, and I believe it solves exactly the problems you are referring to here — i.e. being able to track related Issues across different repos via a central WebGUI, as if they were part of the same project. It's basically a "meta Dashboard" that spans across all the repos you need, allowing you to review PRs, Issues, Bug reports, etc. from one place, and also take actions for these from a single interface.

I intend to do the same changes in the PML repos.

I thought you wanted to keep the PML documentation repos as individual project to be submoduled in view of future localization — PML docs are more likely to be translated to other languages than PMDL docs, because of the wider and less technical target user base.

I know that Git submodules can be a pain in the side, but with proper automation of the toolchain you can have your build tool handle all the nitty gritty associated with submodules initialization and updates — it's very easy to have a script carry out all the necessary checks and operation before executing the build. It would be a "set it and forget it" job, except for the problem of cross-repo PRs for contributors, which are inevitable.

Bear in mind that sub-modules also allow you to keep a clean history of the documentation, whereas with a single repository you end have having alternating commits that target now one document, now another, and interspersed with commits relating to the build toolchain. This also means having to work with multiple devel branches, which is OK when you're working on your own, but can turn things sour when dealing with contributors PRs.

In any case, before you squash together all the source repos of the various PML documents, you need to come up with a good development and contributions strategy in order to guide and coordinate the dev branches of each document, before merging them into main. And these guidelines need to be well documented in the repository, for the benefit of contributors.

Without such a strategy, juggling contributions to all these different documents — for both their current- and upcoming-version (i.e. next PMLC release) — is going to become real messy and will result in tons of conflicts that will block merge and rebase operations. Submodules are immune to this, since while on disk they look as if part of their host repository, in reality they remain independent repositories, where the host repo acts like a cement binding them together by deciding which checkout each subfolder (=submodule) should point to.

[pml-lang]

in the current situation it probably makes more sense to keep things simple and store all the material under a single umbrella repository. If in the future a real need arises to justify sub-moduling the sources to facilitate other projects, you can always do it ...

Exactly! At the moment I really want to keep it simple and start with a single repo for the PDML and PML websites.

enabling the new Dashboard features

I'll do that. Thanks for the tip and the time you took to describe the pros and cons of GitHub submodules.