Organizing the GitHub repository

[m-mohr]

As partially discussed during the last meeting, here are some proposals how we could improve this repository:

• Remove colons from file names to allow using the repository on Windows
• Move files into PFS specific folders (for Pandoc, see below) -> Restructure repository #29
• Create GitHub issue templates for PFSes (and assign labels to them automatically so that they pop up automatically in the project board) -> Add issue templates #30
• Make use of milestones and labels in issues and PRs
• Create a project board per PFS so that the authors can easily track issues -> https://github.com/ceos-org/ceos-ard/projects
• Enable branch protections for main, all changes need to go through PRs with at least one reviewer accepting and CI
• "Purify" documents to be mostly Markdown (not so much HTML), apply linting rules, clean-up, etc. => Add linter for Markdown documents #33
  • AR PFS => Add linter for Markdown documents #33 and Word rendering for Markdown #32
  • SR PFS => Further linting of PFSes #37
  • NLSR PFS => Further linting of PFSes #37
  • ST PFS => Further linting of PFSes #37
  • ST Appendices => Further linting of PFSes #37
  • SAR PFS
    • General lint => Further linting of PFSes #37
    • HTML Tables => Further linting of PFSes #37
    • Linebreaks in tables
  • SAR Appendices
    • General lint => Further linting of PFSes #37
    • Math doesn't show equation labels
  • Template
• CI:
  • Set up CI that automatically generates PDF and Word versions from Markdown (via Pandoc) - latest draft => Word rendering for Markdown #32
  • Set up Markdown linting (also in CI) to avoid errors in markdown and ensure some consistency => Add linter for Markdown documents #33
  • Set up a release workflow (e.g. deploy versioned PDFs and Word documents to GitHub pages)
• Add instructions on how to tun CI locally and how the release process could work

Happy to help to set this up if people are happy with the proposals.

[avalentino]

I would be happy to help too.

[akerosenqvist]

Not knowing much about GitHub but your suggestions above seem to make sense (as does #29)

[libbyrose]

Thanks Matthias. Happy for you to re-organise as helpful to the team - let me know if there are specific items I can help with.

[m-mohr]

@avalentino I've completed all the basic tasks, but feel free to take over any of the CI related work.

[libbyrose]

Sorry - appears when I merged it closed this!

[m-mohr]

No worries, not your fault. It's a GitHub thing ;-)

[gamedaygeorge]

@m-mohr Adding this discussion from #32. This does seem like a future topic, and perhaps needs a bit more context and a specific use case to work out if machine readability is desired, and if so how best to implement.

Looking down the track, another question: could this approach be used to automate the process in other useful ways? e.g. does this make the PFS more machine readable, opening up the possibility of scripting or tools reading the PFS directly?

Good question, in principle we could even move away from Markdown and generate this even more automatically from some kind of e.g. YAML files that are a bit more structured. And also we could actually generate them from individual building blocks so that they may only be written once and are re-used in the PFSes. But maybe that's a step for the future...?

[m-mohr]

I'm running into more and more issues with Markdown. The Markdown syntax is too simple for what we are trying to achieve here, especially with vasts amounts of tables. => #38