1# Contributing
2
3<!-- toc -->
4- [Welcome](#welcome)
5- [CI](#ci)
6- [Logistics](#logistics)
7- [Dev](#dev)
8 - [Content](#content)
9 - [Tests](#tests)
10 - [Documentation](#documentation)
11 - [Questions](#questions)
12
13## Welcome
14
15D2's [long-term mission](https://d2lang.com/tour/future/) is to significantly reduce the
16amount of time and effort it takes to create and maintain high-quality diagrams for every
17software team. We started this because we love the idea of creating diagrams with text --
18but it was clear the existing solutions were inadequete in their state and speed of
19execution for this idea to be widely usable.
20
21We've tried our best to avoid the mistakes of the past and take inspiration from the most
22successful modern programming and configuration languages. D2 has built up each step of
23the text-to-diagram pipeline from scratch, rethinking each one from first principles, from
24the dead simple syntax, to the readable compiler, our own SVG renderer, etc.
25
26D2 is committed to making something people want to use. That means contributions don't
27only have to be in the form of pull requests. Your bug reports, plugins, examples,
28discussions of new ideas, help a great deal.
29
30If you'd like to get involved, we're also committed to helping you merge that first pull
31request. You should be able to freely pick up Issues tagged as "good first issue". Those
32will usually include notes on getting started, but if they're missing or insufficient,
33just leave a comment and we'll add more detail. If you need help getting started, please
34don't hesitate to pop into Discord -- as long as you want to help, we'll find the perfect
35task (complexity matches your appetite and programming experience, in an area you're
36interested in, etc).
37
38## CI
39
40Most of D2's CI is open sourced in its own
41[repository](https://github.com/terrastruct/ci), included as a submodule. After you clone
42D2, make sure you initialize the submodules:
43
44```sh
45git submodule update --init --recursive
46```
47
48`./make.sh` runs everything. Subcommands to run individual parts of the CI:
49
50- `./make.sh fmt`
51- `./make.sh lint`
52- `./make.sh test`
53- `./make.sh race`
54- `./make.sh build`
55
56Here's what a successful run should look like:
57
58<img width="1582" alt="Screen Shot 2023-02-19 at 7 46 34 PM" src="https://user-images.githubusercontent.com/3120367/220004975-7a218b82-c5c1-4a71-b2bb-8695bbfd600c.png">
59
60
61Please make sure CI is passing for any PRs submitted for review.
62
63Be sure to update the submodule whenever there are changes:
64
65```sh
66git submodule update --recursive
67```
68
69## Logistics
70
71- Use Go 1.20.
72- Please sign your commits
73 ([https://github.com/terrastruct/d2/pull/557#issuecomment-1367468730](https://github.com/terrastruct/d2/pull/557#issuecomment-1367468730)).
74- D2 uses Issues as TODOs. No auto-closing on staleness.
75- Branch off `master`.
76- If there's an Issue related, include it by adding "[one-word] #[issue]", e.g. "Fixes
77 #123" somewhere in the description.
78- Whenever possible and relevant, include a screenshot or screen-recording.
79
80## Dev
81
82### Content
83
84Unless you've contributed before, it's safest to choose an Issue with a "good first issue"
85label. If you'd like to propose new functionality or change to current functionality,
86please create an Issue first with a proposal. When you start work on an Issue, please
87leave a comment so others know that it's being worked on.
88
89### Tests
90
91D2 has extensive tests, and all code changes must include tests.
92
93With the exception of changes to the renderer, all code should include a package-specific
94test. If it's a visual change, an end-to-end (e2e) test should accompany.
95
96Let's say I make some code changes. I can easily see how this affects the end result by
97running:
98
99```
100./ci/e2ereport.sh -delta
101```
102
103This gives me a nice HMTL output of what the test expected vs what it got (this was a PR
104fixing multi-byte character labels):
105
106
107
108Run `./ci/e2ereport.sh -help` for flags, including how to get deltas for a single test.
109
110If you're testing labels and strings, it's encouraged to use 1-letter strings (`x`) in small
111functional tests to minimally pinpoint issues. If you are testing something that exercises
112variations in strings, or want to mimic more realistic diagram text, it's encouraged you
113generate random strings and words from `fortune`. It gives a good range of the English
114language. (Sometimes it gives controversial sentences -- don't use those.)
115
116Script to generate one line of random text:
117```
118ipsum1() {
119 fortune | head -n1 | sed 's/^ *//;s/ *$//' | tr -d '\n' | tee /dev/stderr | pbcopy
120}
121```
122
123#### Running tests
124
125Run: `./ci/test.sh`
126
127CI runs tests with `-race` to catch potential race conditions. It's much slower, but if
128your machine can run it locally, you can do so with `./make.sh race`.
129
130If you add a new test and run, it will show failure. That's because the vast majority of
131D2's tests are comparing outputs. You don't define the expected output manually. The
132testing library generates it and it's checked into version control if it looks right. So
133for the first run of a new test, it has no expected output, and will fail. To accept the
134 result as the expected, run the test with environment variable `TESTDATA_ACCEPT=1`.
135
136#### Chaos tests
137
138D2 has [chaos tests](https://en.wikipedia.org/wiki/Chaos_engineering) which produce random
139configurations of diagrams. It can be helpful to run a few iterations (N~=100) to spot
140cover your manual tests.
141
142`D2_CHAOS_MAXI=100 D2_CHAOS_N=100 ./ci/test.sh ./d2chaos`
143
144### Documentation
145
146The code itself should be documented as appropriate with Go-style comments. No rules here,
147`GetX()` doesn't need a `// GetX gets X`.
148
149If it's some new functionality, please submit a pull request to document it in the
150language docs:
151[https://github.com/terrastruct/d2-docs](https://github.com/terrastruct/d2-docs).
152
153### Questions
154
155If you have any questions or would like to get more involved, feel free to open an issue
156to discuss publicly, or chat in [Discord](https://discord.gg/NF6X8K4eDq)! If you have a
157private inquiry, feel free to email us at hi@d2lang.com.
View as plain text