From d4dd332c8d1767f411e2bed88b320aa698cbd396 Mon Sep 17 00:00:00 2001 From: Simon Hafner Date: Sun, 14 Jun 2015 20:57:21 -0500 Subject: [PATCH 01/11] initial draft for contributing.md --- contributing.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 contributing.md diff --git a/contributing.md b/contributing.md new file mode 100644 index 0000000000..9c589ae49b --- /dev/null +++ b/contributing.md @@ -0,0 +1,101 @@ +# The git stuff + +[Guide by github, scroll down a bit](https://guides.github.com/activities/contributing-to-open-source/) + +# Deprecation + +Backward compatibility is important, so if you are renaming a proc or +a type, you can use + +```nim +{.deprecated [oldName: new_name].} +``` + +Or you can simply use + +```nim +proc oldProc() {.deprecated.} +``` + +to mark a symbol as deprecated. Works for procs/types/vars/consts, +etc. + +[Deprecated pragma in the manual.](http://nim-lang.org/docs/manual.html#pragmas-deprecated-pragma) + +# Writing tests + +Not all the tests follow this scheme, feel free to change the ones +that don't. Always leave the code cleaner than you found it. + +## Stdlib + +If you change the stdlib (anything under `lib/`), put a test in the +file you changed. Add the tests under an `when isMainModule:` +condition so they only get executed when the tester is building the +file. Each test should be in a separate `block:` statement, such that +each has its own scope. Use boolean conditions and `assert` for the +testing by itself, don't rely on echo statements or similar. + +Sample test: + +```nim +when isMainModule: + block lenTest: + var values: HashSet[int] + assert(not values.isValid) + assert values.len == 0 + assert values.card == 0 + block setIterator: + type pair = tuple[a, b: int] + var a, b = initSet[pair]() + a.incl((2, 3)) + a.incl((3, 2)) + a.incl((2, 3)) + for x, y in a.items: + b.incl((x - 2, y + 1)) + assert a.len == b.card + assert a.len == 2 +``` + +## Compiler + +The tests for the compiler work differently, they are all located in +`tests/`. Each test has its own file, which is different from the +stdlib tests. At the beginning of every test is the expected side of +the test. Possible keys are: + +- output: The expected output, most likely via `echo` +- exitcode: Exit code of the test (via `exit(number)`) +- errormsg: The expected error message +- file: The file the errormsg +- line: The line the errormsg was produced at + +An example for a test: +```nim +discard """ + errormsg: "type mismatch: got (PTest)" +""" + +type + PTest = ref object + +proc test(x: PTest, y: int) = nil + +var buf: PTest +buf.test() +``` + +# Running tests + +You can run the tests with + + ./koch tests + +which will run a good subset of tests. Some tests may fail. + +# Comparing tests + +Because some tests fail in the current `devel` branch, not every fail +after your change is necessarily caused by your changes. + +TODO From 8618530413d68df7fbf8c16ab76d8ef63114f3e2 Mon Sep 17 00:00:00 2001 From: Simon Hafner Date: Mon, 15 Jun 2015 08:34:11 -0500 Subject: [PATCH 02/11] switched over from assert to doAssert for guide --- contributing.md | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/contributing.md b/contributing.md index 9c589ae49b..123fd5668e 100644 --- a/contributing.md +++ b/contributing.md @@ -33,28 +33,19 @@ If you change the stdlib (anything under `lib/`), put a test in the file you changed. Add the tests under an `when isMainModule:` condition so they only get executed when the tester is building the file. Each test should be in a separate `block:` statement, such that -each has its own scope. Use boolean conditions and `assert` for the +each has its own scope. Use boolean conditions and `doAssert` for the testing by itself, don't rely on echo statements or similar. Sample test: ```nim when isMainModule: - block lenTest: - var values: HashSet[int] - assert(not values.isValid) - assert values.len == 0 - assert values.card == 0 - block setIterator: - type pair = tuple[a, b: int] - var a, b = initSet[pair]() - a.incl((2, 3)) - a.incl((3, 2)) - a.incl((2, 3)) - for x, y in a.items: - b.incl((x - 2, y + 1)) - assert a.len == b.card - assert a.len == 2 + block: # newSeqWith tests + var seq2D = newSeqWith(4, newSeq[bool](2)) + seq2D[0][0] = true + seq2D[1][0] = true + seq2D[0][1] = true + doAssert seq2D == @[@[true, true], @[true, false], @[false, false], @[false, false]] ``` ## Compiler From 0d40fd7552e826aa6ce860d101a5bd49548ed785 Mon Sep 17 00:00:00 2001 From: Simon Hafner Date: Thu, 18 Jun 2015 13:51:29 -0500 Subject: [PATCH 03/11] explained how to run the tester to compare commits --- contributing.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/contributing.md b/contributing.md index 123fd5668e..66a57971c0 100644 --- a/contributing.md +++ b/contributing.md @@ -89,4 +89,27 @@ which will run a good subset of tests. Some tests may fail. Because some tests fail in the current `devel` branch, not every fail after your change is necessarily caused by your changes. -TODO +The tester can compare two test runs. First, you need to create the +reference test. You'll also need to the commit id, because that's what +the tester needs to know in order to compare the two. + +```bash +git checkout devel +DEVEL_COMMIT=$(git rev-parse HEAD) +./koch tests +``` + +Then switch over to your changes and run the tester again. + +```bash +git checkout your-changes +./koch tests +``` + +Then you can ask the tester to create a `testresults.html` which will +tell you if any new tests passed/failed. + +```bash +./koch html $DEVEL_COMMIT +(xdg-)open testresults.html +``` From 3d77d2b29fae43469f85dc9db38101d8d16470cf Mon Sep 17 00:00:00 2001 From: Simon Hafner Date: Thu, 18 Jun 2015 13:59:22 -0500 Subject: [PATCH 04/11] switched to ./koch --print html --- contributing.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/contributing.md b/contributing.md index 66a57971c0..52088d693c 100644 --- a/contributing.md +++ b/contributing.md @@ -110,6 +110,5 @@ Then you can ask the tester to create a `testresults.html` which will tell you if any new tests passed/failed. ```bash -./koch html $DEVEL_COMMIT -(xdg-)open testresults.html +./koch --print html $DEVEL_COMMIT ``` From 69ceede3fb363312b0a39042b4887ae2c52d3846 Mon Sep 17 00:00:00 2001 From: Simon Hafner Date: Thu, 18 Jun 2015 15:17:51 -0500 Subject: [PATCH 05/11] switched to contributing.rst --- contributing.md | 114 ----------------------------------------------- contributing.rst | 114 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+), 114 deletions(-) delete mode 100644 contributing.md create mode 100644 contributing.rst diff --git a/contributing.md b/contributing.md deleted file mode 100644 index 52088d693c..0000000000 --- a/contributing.md +++ /dev/null @@ -1,114 +0,0 @@ -# The git stuff - -[Guide by github, scroll down a bit](https://guides.github.com/activities/contributing-to-open-source/) - -# Deprecation - -Backward compatibility is important, so if you are renaming a proc or -a type, you can use - -```nim -{.deprecated [oldName: new_name].} -``` - -Or you can simply use - -```nim -proc oldProc() {.deprecated.} -``` - -to mark a symbol as deprecated. Works for procs/types/vars/consts, -etc. - -[Deprecated pragma in the manual.](http://nim-lang.org/docs/manual.html#pragmas-deprecated-pragma) - -# Writing tests - -Not all the tests follow this scheme, feel free to change the ones -that don't. Always leave the code cleaner than you found it. - -## Stdlib - -If you change the stdlib (anything under `lib/`), put a test in the -file you changed. Add the tests under an `when isMainModule:` -condition so they only get executed when the tester is building the -file. Each test should be in a separate `block:` statement, such that -each has its own scope. Use boolean conditions and `doAssert` for the -testing by itself, don't rely on echo statements or similar. - -Sample test: - -```nim -when isMainModule: - block: # newSeqWith tests - var seq2D = newSeqWith(4, newSeq[bool](2)) - seq2D[0][0] = true - seq2D[1][0] = true - seq2D[0][1] = true - doAssert seq2D == @[@[true, true], @[true, false], @[false, false], @[false, false]] -``` - -## Compiler - -The tests for the compiler work differently, they are all located in -`tests/`. Each test has its own file, which is different from the -stdlib tests. At the beginning of every test is the expected side of -the test. Possible keys are: - -- output: The expected output, most likely via `echo` -- exitcode: Exit code of the test (via `exit(number)`) -- errormsg: The expected error message -- file: The file the errormsg -- line: The line the errormsg was produced at - -An example for a test: -```nim -discard """ - errormsg: "type mismatch: got (PTest)" -""" - -type - PTest = ref object - -proc test(x: PTest, y: int) = nil - -var buf: PTest -buf.test() -``` - -# Running tests - -You can run the tests with - - ./koch tests - -which will run a good subset of tests. Some tests may fail. - -# Comparing tests - -Because some tests fail in the current `devel` branch, not every fail -after your change is necessarily caused by your changes. - -The tester can compare two test runs. First, you need to create the -reference test. You'll also need to the commit id, because that's what -the tester needs to know in order to compare the two. - -```bash -git checkout devel -DEVEL_COMMIT=$(git rev-parse HEAD) -./koch tests -``` - -Then switch over to your changes and run the tester again. - -```bash -git checkout your-changes -./koch tests -``` - -Then you can ask the tester to create a `testresults.html` which will -tell you if any new tests passed/failed. - -```bash -./koch --print html $DEVEL_COMMIT -``` diff --git a/contributing.rst b/contributing.rst new file mode 100644 index 0000000000..1f5653c619 --- /dev/null +++ b/contributing.rst @@ -0,0 +1,114 @@ +The git stuff +============= + +`Guide by github, scroll down a bit`_ + +# Deprecation + +Backward compatibility is important, so if you are renaming a proc or +a type, you can use + + +.. code-block:: nim + {.deprecated [oldName: new_name].} + +Or you can simply use + +.. code-block:: nim + proc oldProc() {.deprecated.} + +to mark a symbol as deprecated. Works for procs/types/vars/consts, +etc. + +`Deprecated pragma in the manual.`_ + +Writing tests +============= + +Not all the tests follow this scheme, feel free to change the ones +that don't. Always leave the code cleaner than you found it. + +Stdlib +------ + +If you change the stdlib (anything under ``lib/``), put a test in the +file you changed. Add the tests under an ``when isMainModule:`` +condition so they only get executed when the tester is building the +file. Each test should be in a separate ``block:`` statement, such that +each has its own scope. Use boolean conditions and ``doAssert`` for the +testing by itself, don't rely on echo statements or similar. + +Sample test: + +.. code-block:: nim + when isMainModule: + block: # newSeqWith tests + var seq2D = newSeqWith(4, newSeq[bool](2)) + seq2D[0][0] = true + seq2D[1][0] = true + seq2D[0][1] = true + doAssert seq2D == @[@[true, true], @[true, false], @[false, false], @[false, false]] + +Compiler +-------- + +The tests for the compiler work differently, they are all located in +``tests/``. Each test has its own file, which is different from the +stdlib tests. At the beginning of every test is the expected side of +the test. Possible keys are: + +- output: The expected output, most likely via ``echo`` +- exitcode: Exit code of the test (via ``exit(number)``) +- errormsg: The expected error message +- file: The file the errormsg +- line: The line the errormsg was produced at + +An example for a test: + +.. code-block:: nim + discard """ + errormsg: "type mismatch: got (PTest)" + + type + PTest = ref object + + proc test(x: PTest, y: int) = nil + + var buf: PTest + buf.test() + +Running tests +============= + +You can run the tests with + +.. code-block:: bash + ./koch tests + +which will run a good subset of tests. Some tests may fail. + +# Comparing tests + +Because some tests fail in the current ``devel`` branch, not every fail +after your change is necessarily caused by your changes. + +The tester can compare two test runs. First, you need to create the +reference test. You'll also need to the commit id, because that's what +the tester needs to know in order to compare the two. + +.. code-block:: bash + git checkout devel + DEVEL_COMMIT=$(git rev-parse HEAD) + ./koch tests + +Then switch over to your changes and run the tester again. + +.. code-block:: bash + git checkout your-changes + ./koch tests + +Then you can ask the tester to create a ``testresults.html`` which will +tell you if any new tests passed/failed. + +.. code-block:: bash + ./koch --print html $DEVEL_COMMIT From 24bb11c7bc3027fb05249c6394c2e078c22fe00c Mon Sep 17 00:00:00 2001 From: Simon Hafner Date: Thu, 18 Jun 2015 15:34:39 -0500 Subject: [PATCH 06/11] fixed some non-rst stuff --- contributing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/contributing.rst b/contributing.rst index 1f5653c619..0b65d7ae16 100644 --- a/contributing.rst +++ b/contributing.rst @@ -87,7 +87,8 @@ You can run the tests with which will run a good subset of tests. Some tests may fail. -# Comparing tests +Comparing tests +=============== Because some tests fail in the current ``devel`` branch, not every fail after your change is necessarily caused by your changes. From 73d95c9e7b4e8ae9c2e85ca3b9e7b2e394337010 Mon Sep 17 00:00:00 2001 From: Simon Hafner Date: Thu, 18 Jun 2015 15:35:22 -0500 Subject: [PATCH 07/11] and some more non-rst stuff fixed --- contributing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/contributing.rst b/contributing.rst index 0b65d7ae16..68265b7c92 100644 --- a/contributing.rst +++ b/contributing.rst @@ -3,7 +3,8 @@ The git stuff `Guide by github, scroll down a bit`_ -# Deprecation +Deprecation +=========== Backward compatibility is important, so if you are renaming a proc or a type, you can use From ab559814d8c53d113b9a46d330246a37612d408a Mon Sep 17 00:00:00 2001 From: Simon Hafner Date: Thu, 18 Jun 2015 16:10:54 -0500 Subject: [PATCH 08/11] fixed the rst code blocks --- contributing.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/contributing.rst b/contributing.rst index 68265b7c92..74b15bf3f1 100644 --- a/contributing.rst +++ b/contributing.rst @@ -11,11 +11,13 @@ a type, you can use .. code-block:: nim + {.deprecated [oldName: new_name].} Or you can simply use .. code-block:: nim + proc oldProc() {.deprecated.} to mark a symbol as deprecated. Works for procs/types/vars/consts, @@ -42,6 +44,7 @@ testing by itself, don't rely on echo statements or similar. Sample test: .. code-block:: nim + when isMainModule: block: # newSeqWith tests var seq2D = newSeqWith(4, newSeq[bool](2)) @@ -67,6 +70,7 @@ the test. Possible keys are: An example for a test: .. code-block:: nim + discard """ errormsg: "type mismatch: got (PTest)" @@ -84,6 +88,7 @@ Running tests You can run the tests with .. code-block:: bash + ./koch tests which will run a good subset of tests. Some tests may fail. @@ -99,6 +104,7 @@ reference test. You'll also need to the commit id, because that's what the tester needs to know in order to compare the two. .. code-block:: bash + git checkout devel DEVEL_COMMIT=$(git rev-parse HEAD) ./koch tests @@ -106,6 +112,7 @@ the tester needs to know in order to compare the two. Then switch over to your changes and run the tester again. .. code-block:: bash + git checkout your-changes ./koch tests @@ -113,4 +120,5 @@ Then you can ask the tester to create a ``testresults.html`` which will tell you if any new tests passed/failed. .. code-block:: bash + ./koch --print html $DEVEL_COMMIT From 17d2ab82a86d49d3b296fef888ef644cc42ee623 Mon Sep 17 00:00:00 2001 From: Simon Hafner Date: Thu, 18 Jun 2015 16:27:10 -0500 Subject: [PATCH 09/11] fixed rst links --- contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing.rst b/contributing.rst index 74b15bf3f1..31ffcccedc 100644 --- a/contributing.rst +++ b/contributing.rst @@ -1,7 +1,7 @@ The git stuff ============= -`Guide by github, scroll down a bit`_ +`Guide by github, scroll down a bit `_ Deprecation =========== @@ -23,7 +23,7 @@ Or you can simply use to mark a symbol as deprecated. Works for procs/types/vars/consts, etc. -`Deprecated pragma in the manual.`_ +`Deprecated pragma in the manual. `_ Writing tests ============= From ef9dd0d4c5d8c1a547b557573bc782b92ea5abbf Mon Sep 17 00:00:00 2001 From: Simon Hafner Date: Thu, 18 Jun 2015 17:47:33 -0500 Subject: [PATCH 10/11] added comment about failing tests and categories --- contributing.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/contributing.rst b/contributing.rst index 31ffcccedc..745db23778 100644 --- a/contributing.rst +++ b/contributing.rst @@ -91,7 +91,19 @@ You can run the tests with ./koch tests -which will run a good subset of tests. Some tests may fail. +which will run a good subset of tests. Some tests may fail. If you +only want to run failing tests, go for + +.. code-block:: bash + + ./koch tests --failing all + +You can also run only a single category of tests. For a list of +categories, see ``tests/testament/categories.nim``, at the bottom. + +.. code-block:: bash + + ./koch tests c lib Comparing tests =============== From acc8d3746686a1797a9986b0aef78a7053cdd7dc Mon Sep 17 00:00:00 2001 From: Simon Hafner Date: Fri, 19 Jun 2015 10:32:29 -0500 Subject: [PATCH 11/11] closed the discard in the guide --- contributing.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/contributing.rst b/contributing.rst index 745db23778..8e669c6143 100644 --- a/contributing.rst +++ b/contributing.rst @@ -73,6 +73,7 @@ An example for a test: discard """ errormsg: "type mismatch: got (PTest)" + """ type PTest = ref object