Commit a37ea5acf3d98824c64c2859ed72d6203c4de4bb | zig

author	Andrew Kelley <andrew@ziglang.org> 2019-05-28 14:50:02-04:00
committer	Andrew Kelley <andrew@ziglang.org> 2019-05-28 14:50:02-04:00
log	a37ea5acf3d98824c64c2859ed72d6203c4de4bb
tree	64785d8df48d4166dd4cea60d97d1fe14e422832
parent	8a65478801f8d41d3e62826e99ec23163051a9f0
signature	Commit is signed but in an unrecognized format.

extract CONTRIBUTING.md from README.md

2 files changed, 91 insertions(+), 92 deletions(-)

CONTRIBUTING.md
README.md

CONTRIBUTING.md created+91

...	@@ -0,0 +1,91 @@
1	## Contributing
2
3	### Start a Project Using Zig
4
5	One of the best ways you can contribute to Zig is to start using it for a
6	personal project. Here are some great examples:
7
8	* [Oxid](https://github.com/dbandstra/oxid) - arcade style game
9	* [TM35-Metronome](https://github.com/TM35-Metronome) - tools for modifying and randomizing Pokémon games
10	* [trOS](https://github.com/sjdh02/trOS) - tiny aarch64 baremetal OS thingy
11
12	Without fail, these projects lead to discovering bugs and helping flesh out use
13	cases, which lead to further design iterations of Zig. Importantly, each issue
14	found this way comes with real world motivations, so it is easy to explain
15	your reasoning behind proposals and feature requests.
16
17	Ideally, such a project will help you to learn new skills and add something
18	to your personal portfolio at the same time.
19
20	### Spread the Word
21
22	Another way to contribute is to write about Zig, or speak about Zig at a
23	conference, or do either of those things for your project which uses Zig.
24	Here are some examples:
25
26	* [Iterative Replacement of C with Zig](http://tiehuis.github.io/blog/zig1.html)
27	* [The Right Tool for the Right Job: Redis Modules & Zig](https://www.youtube.com/watch?v=eCHM8-_poZY)
28
29	Zig is a brand new language, with no advertising budget. Word of mouth is the
30	only way people find out about the project, and the more people hear about it,
31	the more people will use it, and the better chance we have to take over the
32	world.
33
34	### Finding Contributor Friendly Issues
35
36	Please note that issues labeled
37	[Proposal](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aproposal)
38	but do not also have the
39	[Accepted](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted)
40	label are still under consideration, and efforts to implement such a proposal
41	have a high risk of being wasted. If you are interested in a proposal which is
42	still under consideration, please express your interest in the issue tracker,
43	providing extra insights and considerations that others have not yet expressed.
44	The most highly regarded argument in such a discussion is a real world use case.
45
46	The issue label
47	[Contributor Friendly](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3A%22contributor+friendly%22)
48	exists to help contributors find issues that are "limited in scope and/or
49	knowledge of Zig internals."
50
51	### Editing Source Code
52
53	First, build the Stage 1 compiler as described in [the Building section](#building).
54
55	When making changes to the standard library, be sure to edit the files in the
56	`std` directory and not the installed copy in the build directory. If you add a
57	new file to the standard library, you must also add the file path in
58	CMakeLists.txt.
59
60	To test changes, do the following from the build directory:
61
62	1. Run `make install` (on POSIX) or
63	`msbuild -p:Configuration=Release INSTALL.vcxproj` (on Windows).
64	2. `bin/zig build --build-file ../build.zig test` (on POSIX) or
65	`bin\zig.exe build --build-file ..\build.zig test` (on Windows).
66
67	That runs the whole test suite, which does a lot of extra testing that you
68	likely won't always need, and can take upwards of 2 hours. This is what the
69	CI server runs when you make a pull request.
70
71	To save time, you can add the `--help` option to the `zig build` command and
72	see what options are available. One of the most helpful ones is
73	`-Dskip-release`. Adding this option to the command in step 2 above will take
74	the time down from around 2 hours to about 6 minutes, and this is a good
75	enough amount of testing before making a pull request.
76
77	Another example is choosing a different set of things to test. For example,
78	`test-std` instead of `test` will only run the standard library tests, and
79	not the other ones. Combining this suggestion with the previous one, you could
80	do this:
81
82	`bin/zig build --build-file ../build.zig test-std -Dskip-release` (on POSIX) or
83	`bin\zig.exe build --build-file ..\build.zig test-std -Dskip-release` (on Windows).
84
85	This will run only the standard library tests, in debug mode only, for all
86	targets (it will cross-compile the tests for non-native targets but not run
87	them).
88
89	When making changes to the compiler source code, the most helpful test step to
90	run is `test-behavior`. When editing documentation it is `docs`. You can find
91	this information and more in the `--help` menu.

README.md-92

...	@@ -96,95 +96,3 @@ use stage 1.	...	@@ -96,95 +96,3 @@ use stage 1.
96	```	96	```
97	./stage2/bin/zig build --build-file ../build.zig install -Drelease-fast	97	./stage2/bin/zig build --build-file ../build.zig install -Drelease-fast
98	```	98	```
99
100	## Contributing
101
102	### Start a Project Using Zig
103
104	One of the best ways you can contribute to Zig is to start using it for a
105	personal project. Here are some great examples:
106
107	* [Oxid](https://github.com/dbandstra/oxid) - arcade style game
108	* [TM35-Metronome](https://github.com/TM35-Metronome) - tools for modifying and randomizing Pokémon games
109	* [trOS](https://github.com/sjdh02/trOS) - tiny aarch64 baremetal OS thingy
110
111	Without fail, these projects lead to discovering bugs and helping flesh out use
112	cases, which lead to further design iterations of Zig. Importantly, each issue
113	found this way comes with real world motivations, so it is easy to explain
114	your reasoning behind proposals and feature requests.
115
116	Ideally, such a project will help you to learn new skills and add something
117	to your personal portfolio at the same time.
118
119	### Spread the Word
120
121	Another way to contribute is to write about Zig, or speak about Zig at a
122	conference, or do either of those things for your project which uses Zig.
123	Here are some examples:
124
125	* [Iterative Replacement of C with Zig](http://tiehuis.github.io/blog/zig1.html)
126	* [The Right Tool for the Right Job: Redis Modules & Zig](https://www.youtube.com/watch?v=eCHM8-_poZY)
127
128	Zig is a brand new language, with no advertising budget. Word of mouth is the
129	only way people find out about the project, and the more people hear about it,
130	the more people will use it, and the better chance we have to take over the
131	world.
132
133	### Finding Contributor Friendly Issues
134
135	Please note that issues labeled
136	[Proposal](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aproposal)
137	but do not also have the
138	[Accepted](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3Aaccepted)
139	label are still under consideration, and efforts to implement such a proposal
140	have a high risk of being wasted. If you are interested in a proposal which is
141	still under consideration, please express your interest in the issue tracker,
142	providing extra insights and considerations that others have not yet expressed.
143	The most highly regarded argument in such a discussion is a real world use case.
144
145	The issue label
146	[Contributor Friendly](https://github.com/ziglang/zig/issues?q=is%3Aissue+is%3Aopen+label%3A%22contributor+friendly%22)
147	exists to help contributors find issues that are "limited in scope and/or
148	knowledge of Zig internals."
149
150	### Editing Source Code
151
152	First, build the Stage 1 compiler as described in [the Building section](#building).
153
154	When making changes to the standard library, be sure to edit the files in the
155	`std` directory and not the installed copy in the build directory. If you add a
156	new file to the standard library, you must also add the file path in
157	CMakeLists.txt.
158
159	To test changes, do the following from the build directory:
160
161	1. Run `make install` (on POSIX) or
162	`msbuild -p:Configuration=Release INSTALL.vcxproj` (on Windows).
163	2. `bin/zig build --build-file ../build.zig test` (on POSIX) or
164	`bin\zig.exe build --build-file ..\build.zig test` (on Windows).
165
166	That runs the whole test suite, which does a lot of extra testing that you
167	likely won't always need, and can take upwards of 2 hours. This is what the
168	CI server runs when you make a pull request.
169
170	To save time, you can add the `--help` option to the `zig build` command and
171	see what options are available. One of the most helpful ones is
172	`-Dskip-release`. Adding this option to the command in step 2 above will take
173	the time down from around 2 hours to about 6 minutes, and this is a good
174	enough amount of testing before making a pull request.
175
176	Another example is choosing a different set of things to test. For example,
177	`test-std` instead of `test` will only run the standard library tests, and
178	not the other ones. Combining this suggestion with the previous one, you could
179	do this:
180
181	`bin/zig build --build-file ../build.zig test-std -Dskip-release` (on POSIX) or
182	`bin\zig.exe build --build-file ..\build.zig test-std -Dskip-release` (on Windows).
183
184	This will run only the standard library tests, in debug mode only, for all
185	targets (it will cross-compile the tests for non-native targets but not run
186	them).
187
188	When making changes to the compiler source code, the most helpful test step to
189	run is `test-behavior`. When editing documentation it is `docs`. You can find
190	this information and more in the `--help` menu.