Add codebase.md#87
Conversation
This commit introduces codebase.md, a comprehensive developer guide tailored for both human contributors and AI agents. It details the bot's driver-based architecture, the database abstraction layer (and the 'long slog' migration from MongoDB to BoltDB), and provides guidance on creating new features and testing handlers. The documentation maintains a 'funny but accurate' tone as requested, incorporating project history and the collective disdain for MongoDB. Co-authored-by: candour <4670475+candour@users.noreply.github.com>
…779322245 Add codebase.md developer documentation
|
Bots and humans won't read https://github.com/fluffle/sp0rkle/wiki so should that be copied into here (or maybe Should this he named AGENTS.md? |
|
|
||
| ## 5. Pro-Tips and Pitfalls | ||
|
|
||
| - **The Global `bot`**: The `bot` package uses a global singleton. It's not "modern Go," but it works. Just be careful with state. |
There was a problem hiding this comment.
Suggestions, define how to be careful. What false assumptions might humans & AI have if they are used to more modern Go
|
|
||
| - **The Global `bot`**: The `bot` package uses a global singleton. It's not "modern Go," but it works. Just be careful with state. | ||
| - **Data Loss (The Mongo Curse)**: We hate MongoDB. That's why we're migrating. If you find a data mismatch between Mongo and Bolt, the `db.Both` layer will log a warning. Listen to it. | ||
| - **Regex is Your Friend (and Enemy)**: Much of sp0rkle's parsing relies on regex. Use `util/lexer.go` if you want to parse complex strings without descending into madness. |
There was a problem hiding this comment.
Ensure unit tests are added for positive, negative and edge cases.
| - **The Global `bot`**: The `bot` package uses a global singleton. It's not "modern Go," but it works. Just be careful with state. | ||
| - **Data Loss (The Mongo Curse)**: We hate MongoDB. That's why we're migrating. If you find a data mismatch between Mongo and Bolt, the `db.Both` layer will log a warning. Listen to it. | ||
| - **Regex is Your Friend (and Enemy)**: Much of sp0rkle's parsing relies on regex. Use `util/lexer.go` if you want to parse complex strings without descending into madness. | ||
| - **Pollers**: If your feature needs to do something periodically (like checking an RSS feed), use `bot.Poll(myPoller)`. |
There was a problem hiding this comment.
Pollers are shit, architecturally. They need to be completely decoupled from the connection lifecycle so they can be stopped and started arbitrarily. Also I think I got the API wrong. Needs some thought.
I wouldn't recommend using them in their current state even if they do just about solve the "recurring event" problem.
| 1. Install Go and MongoDB (if you must). | ||
| 2. Run `go build` in the root. | ||
| 3. Run the bot: `./sp0rkle --servers irc.yournet.org --nick mybot --channels "#test"`. | ||
| 4. If you need a database backup, see `backup.sh`. If you lose your data because you didn't have a backup... well, that's the sp0rkle way. |
There was a problem hiding this comment.
well, that's the sp0rkle way.
sick burn
sp0rkle has not lost data in >20 years now :-)
fluffle
left a comment
fluffle
left a comment
There was a problem hiding this comment.
It's been too long for me to actually have proper context any more, but thanks for sending this :-)
|
Traditionally when reviews happen and comments are made the author goes back to the PR and addresses the comments before it's merged. Call me old-fashioned but I think that's still a valid thing to expect. I don't know how we make Jules do that -- perhaps I needed to "request changes" rather than just snarking -- but you had some valid requests and I think they were worth getting the AI to expend some more tokens on. |
|
Let's try: @google-labs-jules please address @gundalow's requests to add additional suggestions on unit testing and "how to be careful". |
Oh, I meant after this is merged. ie resolve all the above comments before merging.
|
|
@google-labs-jules please address @gundalow's requests to add additional suggestions on unit testing and "how to be careful". |
|
@jules please respond to the PR comments |
…GENTS.md Co-authored-by: candour <4670475+candour@users.noreply.github.com>
3 participants
Describes the code base
This change is