Better contributor docs

[jcbhmr]

This is related to #69 and #75 , but tackles the improvement of developer guides instead of user guides.

Does a Wiki make sense for developer-focused docs? I actively wish 👍✅ or 👎⛔ opinions to see if something else would be better/wanted.

Tasks

• Add an actual guide/walkthrough to create a new feature somewhere (GitHub Wiki or CONTRIBUTING.md)
• Create a Wiki based on my docs philosophy (see below) with all the nitty gritty guides to add/modify stuff and patterns to follow
  • Detail why we need a check_package function
  • Describe why the repo is structured the way it is (src and test)
  • Explain what that magical source dev-container-features-test-lib does
  • Explain why these features are all grouped in one repo instead of separate repos
  • Explain what exec $SHELL does
• Trim some of the auto-generated fat off of the CONTRIBUTING.md? 🟨 Is this a good idea?

My personal documentation philosophy

🔴🔴🔴 This is NOT a guide! This is my own opinion! This is how I structure my own docs. You don't have to adopt this. 🔴🔴🔴

I find that it helps to segment your documentation based on your audience. This means that:

• A little bit of everything goes in the README.md (it's where everyone goes). If it's small enough, you can only use a README.
• Guides on how to format code for PR, how to open issues, etc. go in CONTRIBUTING.md. It's for GitHub-related stuff and "what you need to do to contribute" like:
  • Code styles
  • How to pick out good beginner issues
  • Any special PR guidelines like "Ping @ if you change $X"
  • How to go about contributing back
  • Pointers to parts of the Wiki for dev-specific docs
• Developer docs like... (below) go in the GitHub Wiki. Why? It's not Google-indexed so it doesn't confuse actual "I want to install this" users, and it still acts like a sort-of website.
  • How to install dependencies
  • What dependencies are needed to build the binary
  • What the different make or npm or whatever commands/scripts do
  • How to add new features
  • How it's laid out
  • Why certain tooling/deps are used. Why use pyautogui over pywinauto? In the Wiki.
  • A brief explainer of architecture (Answer "What services does it use?" with something like "It uses Vercel on the backend with React on the frontend and has a Python-powered REST API for ...")
• User docs go on GitHub Pages or some other legitimate Google-indexable website. This allows Google searches to actually function. Examples on how to use things also go here. Think something like Docusaurus. Think JavaDoc & usage guide. Think like TypeScript's website.

Of course, not all projects have these "segments" of documentation; some don't have a need for developer docs, some don't need user docs, some don't need a website, etc.

⚠️ This is just how I @jcbhmr do things/think of things. It is not necessarily right or what should be done with this repo.

ℹ About the wiki: I always try to keep the Wiki Markdown docs in source control, then sync them to the GitHub public wiki tab on pushes to main via a GitHub Action. This lets PRs affect the docs instead of there only being one copy. Here's a GitHub Action that does this.

If we do make a Wiki for explanations, I recommend that it be tied to a wiki/ folder auto-synced on each push to the actual "published" Wiki tab on GitHub. Sure you could just link to the wiki/Your-title-here.md files like https://github.com/user/repo/tree/main/blob/wiki/Your-title-here.md, but I think it's nicer with the Wiki's auto-generated sidebar, Table of Contents, etc. It's more "website"-looking. Here's a GitHub Action that does this

[DaneWeber]

If it's helpful, I have a tiny contribution to the CONTRIBUTING doc here, but obviously do with it what you will. I'm happy to see that answering some of the questions I had is on your todo list. #134

Separately: please add a real email for security issues soon (or other instructions for reporting security issues) --> https://github.com/devcontainers-contrib/features/blame/main/CONTRIBUTING.md#L48

[jcbhmr]

@DaneWeber Good catch on the security email! 😨