Create a FileList to guide the curious and new contributors

[merriam]

Is your proposal related to a problem?

Exploring the create-react-app package is daunting. The source code to the package is massive, at about one hundred directories and it takes some hours to understand the layout of directories and configuration files. This is an effort repeated by anyone curious how the package works or anyone making a significant contribution to the project.

Describe the solution you'd like

I would like to contribute a FileList. This would give brief explanations of the interesting directories and configuration of the project. I spend a few hours getting into a new project just understanding what packages are used, how everything is laid out, and what configuration files do what. The effort is one repeated by every new person getting into a project and could be far easier with a bit of documentation. This is a documentation-only change adding documentation for new developers and explorers of create-react-app.

The entire contribution would be a FileList.txt. It would include a directory tree:

Project Directory Tree
+  .
+--+  .github                            Configurations for github.com (repository)
+--+--+  ISSUE_TEMPLATE                  Templates used for new GitHub issues
+--+--+  workflows                       Configuration files for automated tasks on github.com
+--+  docusaurus                         Root for Docusaurus (static site builder)
+--+--+  docs                            Topics in sidebar of website
+--+--+  website                         Website at https://create-react-app.dev/docs
+--+--+--+  src                          Source for https://create-react-app.dev/docs/getting-started
+--+--+--+--+  css                       Cascading Style Sheets for web presentation
...

and directory listings of some of the directories:

Directory .
    Files:
        .alexignore                      Patterns for files ignored by Alex (polarizing phrasing checker)
        .alexrc                          Extra allowances for Alex (polarizing phrasing checker)
        .eslintignore                    Patterns for files ignored by ESLint (Javascript linter)
        .eslintrc.json                   JSON configuration for ESLint (Javascript linter)
        .gitattributes                   Set EOL to \n on commit
        .gitignore                       Patterns for files not to placed in git (source control)
        .prettierignore                  Patterns for files ignored by Prettier (code formatter)
        .prettierrc                      JSON configuration for Prettier (code formatter)
        azure-pipelines.yml              Azure Pipelines (CI build cloud) for multiplatform test
        azure-pipelines-test-job.yml     Azure pipeline job to test per platform
        CHANGELOG.md                     Changes to version 5.0.0 to  5.0.1
        CHANGELOG-0.x.md                 Change log for version 0.1.0 to 0.9.5
        CHANGELOG-1.x.md                 Change log for versions 1.0.1 to 1.1.5
        CHANGELOG-2.x.md                 Change log for version 2.0.3 to 2.1.8
        CHANGELOG-3.x.md                 Change log versions 3.0.0 to 3.4.4
        CHANGELOG-4.x.md                 Change log for version 4.0.0 to 4.0.3
...

Describe alternatives you've considered

I considered writing an overview architecture document, basically a long blog post about the architecture. This approach has several drawbacks: it is inherently opinionated, the CRA architecture is distinct from the architecture of its included packages, and, most importantly, such a document is brittle in maintainability and the value of the information if out of date. I decided against writing this document.

I also considered a glossary page. Most developers will know of several technologies like prettier, alex, azure pipelines, github actions, and docusaurus. Few will know all of them. A glossary has a tendency to grow into a dictionary as well meaning people expand definitions and add more definitions. Further, the material is inherently based in the file structure of the project. For example, a mention of alex would need to mention that the ./.alexrc file is used for configuration. While the idea of making a great software development dictionary tickles my mind, its not appropriate now.

Finally, HTML files can have lots of tooltips and graphical views of the project.

I keep coming back to the value of terse descriptions. The descriptions cannot be generated by an IDE and provide the needed information for developers to safely ignore entire directories when working on a problem.

Additional context

The only remaining niggle is my lack of a testing plan. I cobbled together a little program that helps me maintain the descriptions, scans the directories and lets me generate a FileList. I am fairly certain that I will not miss files or directories by accident. There is a possibility of wildly incorrect descriptions for which I can only rely on comments to the issue. Testing is still done by my eyeballs, however.

Fortunately, the directory structure and names of configuration files change slowly. Usually a short hint is all that is necessary to grok their meanings. This makes me more comfortable with a lack of testing plan and being the primary maintainer of the text file.

Please comment. This issue likely falls outside the domains of any individual project member and can therefore fall into a black hole.