OptimisticDev/rfcs
2
1
Fork 0
forked from kaboom-standards-organization/rfcs
Code Pull requests Activity

RFC 0001: Update scope, add troubleshooting, resources and common

Browse source
This commit is contained in:
OptimisticDev 2024-06-26 03:42:38 +00:00
parent 05d270b34e
commit 9d69fa618b
Signed by: OptimisticDev
SSH key fingerprint: SHA256:efAXeDMyuFt1iia2xaqlrcHPlsXcjQEWNA2tmvVTqK8
1 changed files with 20 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
rfcs/0001-Code_Guides.md
View file

@ -7,9 +7,11 @@ This RFC details the targeted scope and formatting of [Guide wiki](https://code.
## Scope
The guides for these libraries must not introduce the reader to the basic concept of programming and the syntax of the programming languages the bot libraries target.
However, as these guides are primarily intended to help get programmers off their feet when starting with a new bot library, it is somewhat likely that it will be the first time someone attempts to program, so things that violate conventional, real-life logic but does not violate programmer/program logic (i.e. indexes starting from 0 instead of 1).
It must attempt to introduce the reader to the peculiarities of the programming language when it is certain that bot development will inevitably run into such peculiarities.
However, as these guides are geared towards beginners to bot development, it is still very likely that there will still be some people entirely new to programming.
As such, deviations from conventional wisdom should be well documented - for example, this would mean documenting the fact that in most programming languages, indexes start from 0 instead of 1.
Such things must be documented, even if they aren't the aim of the code guides, as they will inevitably need to be tackled in bot development.
It must also attempt to illustrate unique design choices in the bot libraries it describes.
### Tooling
@ -21,3 +23,19 @@ The guide should attempt to tell the user what programs (IDEs, compilers and IDE
A guide about a library for Javascript would recommend that the user should install Visual Studio Code and use the npm package manager but also mention that yarn exists.
A guide about a library for Rust would recommend that the user should install Visual Studio Code, install Rust with rustup, use the cargo package manager, use the rust-analyzer extension but also mention that JetBrains provide RustRover.
A guide about a library for Java would recommend that the user should install IntelliJ Idea, install the JDK through IntelliJ and use Gradle for compilation but also mention that Eclipse and Maven exist.
### Useful Resources
Guides should also link to resources that may be useful when troubleshooting issues not covered by the guide and for general library discovery.
For example, all guides would link to [Wiki VG](https://wiki.vg), or it would be linked in the common ground page, and a guide for NMP would link to [minecraft-data documentation](https://prismarinejs.github.io/minecraft-data/?v=1.20.4&d=protocol).
### Troubleshooting
The author of the guide should also attempt to identify common pitfalls in bot development (for example, not responding to the clientbound position update packet with an accept teleport packet, that sort of thing) and add a section to the guide, under a Troubleshooting section, that details why the issue occurs and how to solve it.
## Common Ground
Guides are likely to have some sort of common ground.
As such, to avoid repeating ourselves in documentation and to make updating documentation easier when something major in the protocol changes, a page that details common ground between protocol libraries should be established.
This common ground page would be appended to once we identify duplication between code guides, and would be linked to whenever the common ground would come up in such guides.