Skip to content

Commit a10321b

Browse files
zoffixznetzoffixznet
committed
Move "contributing" doc to its own file
So it's picked up by GitHub and is announced on Issue/PR submission
1 parent 6b84580 commit a10321b

File tree

2 files changed

+147
-144
lines changed

2 files changed

+147
-144
lines changed

‎CONTRIBUTING.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Contributing
2+
3+
A person who wants to contribute a test to the project should read
4+
this Github guide to
5+
issues and [pull requests](http://help.github.com/categories/collaborating-with-issues-and-pull-requests)
6+
(PRs) which describes in great detail the work flow for forks and
7+
submitting PRs to a project.
8+
9+
Follow the same general steps for project `github.com/perl6/roast`:
10+
11+
- fork project `roast`
12+
- clone your fork of `roast` to a local directory
13+
- set the origin and upstream remotes
14+
- checkout a branch to work on your issue or proposal
15+
- see [below](#working-the-issue) for details
16+
- when through, ensure all desired commits are finished
17+
- push the issue branch to your origin (your fork of `roast` on github)
18+
- go to your github account for project `roast` and submit the PR
19+
20+
### Working the issue
21+
22+
#### Normal tests
23+
24+
New tests for existing features are usually accomplished by adding
25+
the test(s) to an existing test file. Then that file's `plan` count is
26+
updated. The new test(s) are tested locally by executing
27+
28+
```perl6
29+
$ perl6 <test file(s)>
30+
```
31+
32+
When all is well, the commits are finalized, the branch is pushed
33+
to the user's fork on Github, and there the PR is initiated.
34+
35+
If a new test file has been created, one additional step has to be
36+
taken: the new test file has to be added to
37+
`github.com/rakudo/rakudo/t/spectest.data` and a PR for project
38+
`github.com/rakudo/rakudo` can be submitted for that. However, it is
39+
easier just to ask for help adding the new test file on IRC channel
40+
`#perl6`.
41+
42+
#### Fudged tests
43+
44+
Let's say you want to propose a new feature, method `printf` for
45+
IO::Handle, for `rakudo` and, being a believer in test-driven
46+
development, are submittng some test for something that can't yet be
47+
tested. Thus we will need to create the test but we will `fudge` it so
48+
it will be ignored.
49+
50+
We create a new test file named appropriately, say, `S16-io/printf.t` ,
51+
the contents of which are:
52+
53+
```perl6
54+
use v6;
55+
use Test;
56+
plan 1;
57+
58+
my $f = './.printf-tmpfil';
59+
my $fh = open $f, :w;
60+
$fh.printf("Hi\n");
61+
$fh.close;
62+
my $res = slurp $f;
63+
is $res, "Hi\n", "printf() works with zero args";
64+
unlink $f;
65+
```
66+
67+
We know the test doesn't work yet:
68+
69+
```perl6
70+
$ perl6 S16-io/printf.t
71+
1..1
72+
No such method 'printf' for invocant of type 'IO::Handle'
73+
in block <unit> at ./S16-io/printf.t line 9
74+
75+
# Looks like you planned 1 test, but ran 0
76+
```
77+
78+
so we add the fudge to it to get the new contents:
79+
80+
```perl6
81+
use v6;
82+
use Test;
83+
plan 1;
84+
85+
#?rakudo skip 'RT #999999 not yet implemented'
86+
{
87+
my $f = './.printf-tmpfil';
88+
my $fh = open $f, :w;
89+
$fh.printf("Hi\n");
90+
$fh.close;
91+
my $res = slurp $f;
92+
is $res, "Hi\n", "printf() works with zero args";
93+
unlink $f;
94+
}
95+
```
96+
97+
Notice we put the test in a block. All tests in that block
98+
are affected by the fudge line preceding it.
99+
100+
We want to test the fudged file before we submit the PR so we have to
101+
manually create the fudged test file:
102+
103+
```perl6
104+
$ fudge rakudo S16-io/printf.t
105+
S16-io/printf.rakudo
106+
```
107+
108+
which, as we see by the return from the command, produces file
109+
`S16-io/printf.rakudo` whose contents are
110+
111+
112+
```perl6
113+
use v6;
114+
use Test;
115+
plan 1;
116+
117+
#?rakudo skip 'RT #999999 not yet implemented'
118+
skip('RT #999999 not yet implemented', 1);# {
119+
# my $f = './.printf-tmpfil';
120+
# my $fh = open $f, :w;
121+
# $fh.printf("Hi\n");
122+
# $fh.close;
123+
# my $res = slurp $f;
124+
# is $res, "Hi\n", "printf() works with zero args";
125+
# unlink $f;
126+
# }
127+
128+
say "# FUDGED!";
129+
exit(1);
130+
```
131+
132+
We can then test it:
133+
134+
```perl6
135+
$ perl6 S16-io/printf.rakudo
136+
1..1
137+
ok 1 - \# SKIP RT \#999999 not yet implemented
138+
# FUDGED!
139+
```
140+
141+
Success! Now we can commit the new test file, but **NOT** the generated fudge
142+
test file&mdash;that will be generated automatically by the test
143+
harness during the regular testing on the servers. As
144+
described earlier, the new test file will have to be added to the spectest.data
145+
file, either via a PR or a request to someone on IRC to add it.

‎README.md

Lines changed: 2 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ as a conforming Perl 6 implementation.
99

1010
- [Environment Variables](#environment-variables)
1111

12-
- [Contributing](#contributing)
12+
- [Contributing](CONTRIBUTING.md)
1313

1414
## Introduction
1515

@@ -122,146 +122,4 @@ too long a time by default so as to make the roast run faster. Defaults to `1`.
122122

123123
## Contributing
124124

125-
A person who wants to contribute a test to the project should read
126-
this Github guide to
127-
issues and [pull requests](http://help.github.com/categories/collaborating-with-issues-and-pull-requests)
128-
(PRs) which describes in great detail the work flow for forks and
129-
submitting PRs to a project.
130-
131-
Follow the same general steps for project `github.com/perl6/roast`:
132-
133-
- fork project `roast`
134-
- clone your fork of `roast` to a local directory
135-
- set the origin and upstream remotes
136-
- checkout a branch to work on your issue or proposal
137-
- see [below](#working-the-issue) for details
138-
- when through, ensure all desired commits are finished
139-
- push the issue branch to your origin (your fork of `roast` on github)
140-
- go to your github account for project `roast` and submit the PR
141-
142-
### Working the issue
143-
144-
#### Normal tests
145-
146-
New tests for existing features are usually accomplished by adding
147-
the test(s) to an existing test file. Then that file's `plan` count is
148-
updated. The new test(s) are tested locally by executing
149-
150-
```perl6
151-
$ perl6 <test file(s)>
152-
```
153-
154-
When all is well, the commits are finalized, the branch is pushed
155-
to the user's fork on Github, and there the PR is initiated.
156-
157-
If a new test file has been created, one additional step has to be
158-
taken: the new test file has to be added to
159-
`github.com/rakudo/rakudo/t/spectest.data` and a PR for project
160-
`github.com/rakudo/rakudo` can be submitted for that. However, it is
161-
easier just to ask for help adding the new test file on IRC channel
162-
`#perl6`.
163-
164-
#### Fudged tests
165-
166-
Let's say you want to propose a new feature, method `printf` for
167-
IO::Handle, for `rakudo` and, being a believer in test-driven
168-
development, are submittng some test for something that can't yet be
169-
tested. Thus we will need to create the test but we will `fudge` it so
170-
it will be ignored.
171-
172-
We create a new test file named appropriately, say, `S16-io/printf.t` ,
173-
the contents of which are:
174-
175-
```perl6
176-
use v6;
177-
use Test;
178-
plan 1;
179-
180-
my $f = './.printf-tmpfil';
181-
my $fh = open $f, :w;
182-
$fh.printf("Hi\n");
183-
$fh.close;
184-
my $res = slurp $f;
185-
is $res, "Hi\n", "printf() works with zero args";
186-
unlink $f;
187-
```
188-
189-
We know the test doesn't work yet:
190-
191-
```perl6
192-
$ perl6 S16-io/printf.t
193-
1..1
194-
No such method 'printf' for invocant of type 'IO::Handle'
195-
in block <unit> at ./S16-io/printf.t line 9
196-
197-
# Looks like you planned 1 test, but ran 0
198-
```
199-
200-
so we add the fudge to it to get the new contents:
201-
202-
```perl6
203-
use v6;
204-
use Test;
205-
plan 1;
206-
207-
#?rakudo skip 'RT #999999 not yet implemented'
208-
{
209-
my $f = './.printf-tmpfil';
210-
my $fh = open $f, :w;
211-
$fh.printf("Hi\n");
212-
$fh.close;
213-
my $res = slurp $f;
214-
is $res, "Hi\n", "printf() works with zero args";
215-
unlink $f;
216-
}
217-
```
218-
219-
Notice we put the test in a block. All tests in that block
220-
are affected by the fudge line preceding it.
221-
222-
We want to test the fudged file before we submit the PR so we have to
223-
manually create the fudged test file:
224-
225-
```perl6
226-
$ fudge rakudo S16-io/printf.t
227-
S16-io/printf.rakudo
228-
```
229-
230-
which, as we see by the return from the command, produces file
231-
`S16-io/printf.rakudo` whose contents are
232-
233-
234-
```perl6
235-
use v6;
236-
use Test;
237-
plan 1;
238-
239-
#?rakudo skip 'RT #999999 not yet implemented'
240-
skip('RT #999999 not yet implemented', 1);# {
241-
# my $f = './.printf-tmpfil';
242-
# my $fh = open $f, :w;
243-
# $fh.printf("Hi\n");
244-
# $fh.close;
245-
# my $res = slurp $f;
246-
# is $res, "Hi\n", "printf() works with zero args";
247-
# unlink $f;
248-
# }
249-
250-
say "# FUDGED!";
251-
exit(1);
252-
```
253-
254-
We can then test it:
255-
256-
```perl6
257-
$ perl6 S16-io/printf.rakudo
258-
1..1
259-
ok 1 - \# SKIP RT \#999999 not yet implemented
260-
# FUDGED!
261-
```
262-
263-
Success! Now we can commit the new test file, but **NOT** the generated fudge
264-
test file&mdash;that will be generated automatically by the test
265-
harness during the regular testing on the servers. As
266-
described earlier, the new test file will have to be added to the spectest.data
267-
file, either via a PR or a request to someone on IRC to add it.
125+
See [CONTRIBUTING.md](CONTRIBUTING.md)

0 commit comments

Comments
 (0)