Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add an ARCHITECTURE.md file #3034

Open
7 tasks
SteveBronder opened this issue Mar 22, 2024 · 2 comments
Open
7 tasks

Add an ARCHITECTURE.md file #3034

SteveBronder opened this issue Mar 22, 2024 · 2 comments

Comments

@SteveBronder
Copy link
Collaborator

SteveBronder commented Mar 22, 2024

Description

@WardBrian brought up the idea of adding an ARCHITECTURE.md file to each of the Stan repos and I really like the idea. A long blog about these files can be found here but essentially it would be a markdown document that goes over each of the folders that exist in the repo, why they exist, and what is inside of them. It would also contain higher level documentation describing how the mechanics of the system work.

For Stan math that would be a file describing

  • Each of fwd/prim/rev along with their subfolders
  • An explanation of how they interconnect i.e. what happens when including only prim, rev, fwd, or all.
  • How we seperate each of these folders with the requires
  • An explainer on how our reverse and forward mode autodiff works, how the arena allocator and reverse pass callback scheme work
  • test folder structure, and overview of the CI setup
  • dependency overview
  • Threading structure

Can anyone else think of more things that should be included in the ARCHITECTURE.md file?

Current Version:

v4.8.1

@WardBrian
Copy link
Member

I have that exact blog post bookmarked for this idea 😉

I think the test folder structure, and overview of the CI setup would also belong.

Perhaps it would be better in the files for stan/cmdstan if they get their own, but an explanation of the various repos and how they are intertwined through submodules or downloading stanc3 would belong as well

@SteveBronder
Copy link
Collaborator Author

Updated initial comment with the test and CI stuff!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants