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	96	```
97	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.