diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 00c17de..0000000 --- a/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2025 Dustin Stiles - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/docs/internals/README.md b/docs/internals/README.md index c672cfd..a49b2a0 100644 --- a/docs/internals/README.md +++ b/docs/internals/README.md @@ -9,4 +9,5 @@ If you want to learn how DSFX works inside, here's what we got: all the code here! - [commit strategy](./commits.md) is the guide for writing commit messages that follow the Conventional Commits specification. +- [hacking](./hacking.md) is the guide for developers who want to contribute to the project. - [handshake](./handshake.md) is the protocol for establishing a secure connection between two parties. diff --git a/docs/internals/hacking.md b/docs/internals/hacking.md new file mode 100644 index 0000000..c844276 --- /dev/null +++ b/docs/internals/hacking.md @@ -0,0 +1,111 @@ +# Hacking + +Welcome fellow hacker! This document is intended to help you get started with the codebase and +understand how to use the various tools and libraries that are included. If you have any questions, +please feel free to reach out to the maintainers. + +**Index** + +- [File Structure](#file-structure) + +--- + +## File Structure + +There are three folders on the top level of the project. They are: + +- [cmd](#cmd) +- [docs](#docs) +- [internal](#internal) + +Files that are stored in the root of the project are generally used for configuration and +documentation purposes, but we try to keep the number of files in the root of the project to a +minimum. + +Currently we have the following files in the top level: + +- `.gitignore` - This file is used to tell git which files and directories to ignore when + committing changes to the repository. +- `CHANGELOG.md` - This file is used to keep track of changes made to the codebase. It is + currently unused and reserved for future use. +- `go.mod` - This file is used to manage the dependencies of the project. It is used by the Go + module system to track the dependencies of the project and ensure that the correct versions are + used. Our project does not have any external dependencies, so this file primarily serves to + establish the project as a Go module. +- `README.md` - This file is used to provide information about the project. It is used to + document the project and provide instructions for how to use it. This file is intended to be + used as a reference for developers and users of the project. + +### cmd + +The `cmd` directory contains entry points for the various tools that are included in the project. +Currently these are the `dsfx` and `dsfxctl` tools. They each define Go `main` packages that can +be compiled and distributed. + +In general, code in this directory should be relevant to the starting, stopping, and running of the +tools. It should not contain any business logic or other code that is not relevant to the tool +itself. Rather, it should delegate to the code in the `internal` directory to do the actual work +and serve as a thin bootstrapping layer. + +### docs + +The `docs` directory contains documentation for the project. Files that are children of this folder +are intended to be viewed by end users. Feel free to peruse around and learn about the system. + +Files that are located in `docs/internals` are **not** intended for end users. They are intended for +developers and contributors to the project. These files are intended to be used as a reference for +understanding the codebase and how it works. The file you are reading right now is located in this +folder. + +### internal + +The `internal` directory contains the core code of the project. This code is not intended for public +use and is meant for internal use only. The code in this directory is organized into several +subdirectories, each of which serves a specific purpose. + +#### internal/client + +This section contains the client code, which is what a user or admin runs on their local machine to +interact with their server (see internal/peer). The client code is responsible for sending and +receiving messages to and from the server, as well as handling user input and output. Currently the +code for the CLI is located in this package, but we would love to see that moved to the `cmd` +folder as it is not applicable to the library side of the tool. The direct consumer of this package +is the `cmd/dsfxctl` main package. + +#### internal/lib + +This section contains shared libraries that are used by the rest of the codebase. They aren't +intended for public use, but can be used freely throughout the rest of the application. Code that +lives in this section should pay close attention to unit tests and benchmarking, as it is likely +used in more than on place, which means that changes here are force multipliers for both bugs and +performance. + +#### internal/peer + +This section contains the peer code, which is what the server runs on the remote machine. The peer +code is responsible for communicating with the client code, other peers, and the filesystem. The +direct consumer of this package is the `cmd/dsfx` main package. + +#### internal/sim + +This section of the codebase contains various helpers for simulating different parts of the system. +You can use these helpers to simulate latency, corruption, and other external factors inside of +your unit tests. + +Currently, these tools are most useful in tests as mock implementations of the system. They are not +intended for production use. When we build out the simulation framework, these tools will mature +and be targeted for that use case. + +#### internal/tool + +This section of the codebase contains various internal tools and scripts that are used for +development, testing, and deployment purposes. These tools are not intended for public use and are +meant for internal use only. Each one is a main package with an executable, usually with a single +command. Some accept command line arguments, you will need to check the code for those. +Alternatively, you may run the tool with `-h` to see the available options. + +The tools in this directory can be loosely compared to a `bin` directory, or maybe a `Makefile`. +We prioritize using Go for our tools, so we try to stay inside of the Go ecosystem as much as +possible. We also try to keep the tools as simple as possible, so that they are easy to use and +understand. It is much better to have a lot of really small, really focused tools than a few +massive tools that do everything.