Study Projects

How to Read a Project

Do not start at the top of the file tree. A large repository read from the first file teaches nothing. Use a method:

1. Pick one question. "How does it evict?" "What happens on a hash collision?" "How is a lookup kept O(log n)?" One question gives you a path through the code.
2. Read the tests first. Tests show the public behavior and the edge cases the authors were afraid of. The _test.go file next to a structure is the best documentation it has.
3. Read the API with go doc. go doc github.com/hashicorp/golang-lru/v2 prints the exported names and comments without opening an editor.
4. Find the core type and its invariants. Every structure has one: "the list is ordered by recency", "keys in a node are sorted", "every level has half the nodes". Find where each method preserves it.
5. Run it. Clone it, run the tests (go test ./...) and the benchmarks (go test -bench . -benchmem). Change one line and see which test fails.
6. Compare with your own version. After a lesson, write the structure from the lesson's demo, then read the library's. The differences (locks, generics, pooling, corner cases) are the lesson.
7. Read the history. git log -p and git blame on a tricky line lead to the issue and the reasoning behind it; bug-fix commits show what went wrong in practice.

Algorithm Collections

The best places to start: many structures in one repository, small files, readable code.

The Go Standard Library

The standard library is the most carefully reviewed Go code there is, and it is part of the golang/go repository, so it costs nothing to read. Browse it on pkg.go.dev (each function has a "source" link) or in the src directory of the repository.

Caches

Storage Engines and Indexes

Databases are where data-structure theory meets disks. These engines are written in Go, are used in serious systems, and are small enough to read.

Compact and Probabilistic Structures

Distributed Systems and Infrastructure

A Reading Plan

Pair each lesson with one reading task and one small experiment:

Contributing

Contributing is how reading becomes skill: someone who knows the project reviews your code. Start small; the first goal is a merged change, not an impressive one.

A Ladder of Contributions

1. Use the project. Build something with it. Every confusing moment is a documentation bug.
2. Read the contribution guide. Look for CONTRIBUTING.md, the issue templates and the code-of-conduct file before writing any code.
3. Fix the small things. Typos and unclear comments, a missing example in the docs, a missing test case for an edge case.
4. Add tests and benchmarks. A test that compares a structure with a slow oracle on random input (the technique used throughout this roadmap) is a valuable contribution to almost any library. So is a fuzz test (Go fuzzing tutorial) or a benchmark for a hot path.
5. Reproduce a bug. Open the issue list, filter by labels such as good first issue or help wanted where the project uses them, and comment before you start so that two people do not do the same work. A failing test that reproduces the bug is already half of the fix.
6. Add or improve an algorithm. In a collection such as TheAlgorithms/Go, check first that the algorithm is not already there, then follow the repository's conventions for layout, documentation and tests.
7. Take on a larger change. Discuss the design in an issue first. Large unannounced pull requests are the ones most often declined.

Before You Send a Change

• Run gofmt -l ., go vet ./... and go test ./..., and fix what they report. Add -race for anything concurrent.
• Keep the change small and about one thing, with a clear title and a description that says what was wrong and how you checked the fix.
• Match the surrounding style, comment density and naming, even where you would have chosen differently.
• Expect review comments. Answer each one, push follow-up commits, and be patient: maintainers are often volunteers.
• Do not paste code you cannot explain, and do not submit code whose license you do not know.

Contributing to Go Itself

The Go project has its own process: changes are reviewed on Gerrit, not through GitHub pull requests, and contributors sign a contributor license agreement. The contribution guide explains the steps. Documentation, examples and tests in the standard library are a realistic place to begin; the x/ repositories, such as golang.org/x/sync and golang.org/x/time, follow the same process.

Practice Lab

1. Diff of two LRUs. Read golang-lru/simplelru and 73_lru_cache.go. List every difference, and say for each whether it is about correctness, speed, or convenience.
2. Oracle for a library. Pick a container from emirpasic/gods and write a random test that checks it against a plain slice or map. Report what you find, even if the answer is that everything agrees.
3. Limiter comparison. Replay the traffic from 74_rate_limiters.go through golang.org/x/time/rate. How many requests does it accept in the boundary test, and why?
4. Read a B-tree. In google/btree, find where a full node is split. Draw the before and after for a node of 3 items, and compare with your notes from Advanced Trees.
5. First contribution. Choose one project from this page and write down: the issue or gap you will address, the file you will change, and the test that will prove it. Submit it.

More material is on the References page. The Demo Examples list has every runnable program in this roadmap.