First pass at Main README.md - Issue #278 #334

sacherjj · 2017-07-25T19:04:47Z

Two places with !!!!!

README.md for each exercise is currently checked in. Should this not happen? I know i just did amends on a bunch, because I didn't have the correct source (even though it is generated later).

Last section, I'm not sure what goes on with /bin. Easiest solution it to not include this at first.

petertseng

thanks. I will probably have more things to say later since I am short on time and can't give this the thorough time it deserves. But it seems you had important questions and so it is good to give an answer to them.

petertseng · 2017-07-25T20:54:58Z

README.md

+
+- Be sure to add it to the appropriate place in the `config.json` file.  Position in the file determines the order exercises are sent.   Generate a unique UUID for the exercise.  Current difficuly levels in use are 1, 4, 7 and 10.
+
+- !!!!! Not sure if this is accurate !!!!!  Also, please run `bin/fetch-configlet && bin/configlet` to ensure the exercise is configured correctly.


Eh... this sentence is accurate in that it is possible to do so. I'm fine with calling this an optional step, since Travis CI will do it anyway.

petertseng · 2017-07-25T20:59:54Z

README.md

+
+- Exercises should use only the Rust core libraries.  If you must use an external crate, see note below about `Cargo-example.toml`.  `Cargo.toml` should not have external dependencies as we don't want to make the user assume which crates are required.
+
+-  !!!!! Not sure if this is accurate !!!!!  Please do not add a README or README.md file to the exercise directory. The READMEs are constructed using shared metadata, which lives in the


you are correct. this is inaccurate. It is possible that exercism/meta#15 will lead to sufficient information to know what to replace it with.

On the other hand, you could also argue that it is not your job to fix this sentence, since it is derived from https://github.com/exercism/request-new-language-track/blob/master/TRACK_README.md . You have first dibs on filing an issue on https://github.com/exercism/request-new-language-track to ask for guidance on replacing this sentence.

If it is necessary, I would accept simply removing this entire bullet point until a proper replacement is determined.

petertseng · 2017-07-25T21:00:14Z

README.md

+---
+
+- An exercise may contain `.meta/hints.md`.  This is optional and will appear after the normal exercise
+  instructions if present.  Rust is different in may ways from other languages.  This is a place where 


may -> many

sacherjj · 2017-07-26T01:35:38Z

Updated addressing those points.

petertseng

I think this will be good. We should put this above the "Rust icon" since it is more important than the icon.

We can delete the line that says "Please see the [contributing guide](https://github.com/exercism/docs/tree/master/contributing-to-language-tracks)" since there is an identical link in the section being added.

petertseng · 2017-07-28T06:27:25Z

README.md

+
+## Contributing a New Exercise ##
+
+- All Exercism exercises must be defined in [problem-specifications](https://github.com/exercism/problem-specifications/tree/master/exercises) before they are implemented for a specific track. Please submit a PR there if your exercise is new to Exercism.


this sentence is no longer true, but that is also not your fault. exercism/generic-track#35

So, I'm going to suggest we write here If a new exercise would potentially be suitable for a track other than the Rust track, it should be defined in [problem-specifications](https://github.com/exercism/problem-specifications/tree/master/exercises) so that other tracks may benefit from it. Or something like that?

petertseng · 2017-07-28T06:28:46Z

README.md

+
+- Watch out for trailing spaces, extra blank lines, and spaces in blank lines.
+
+- All the tests for Rust exercises can be run from the top level of the repo with `_test\check-exercises.sh` Please run this command before submitting your PR.  See [Windows Specific instructions](_test/WINDOWS_README.md) for running this.


I would say / instead of \ in _test\check-exercises.sh, for consistency with other instances of directory separator in this file (exercism/discussions, exercises/exercise/name, etc.)

petertseng · 2017-07-28T06:29:03Z

README.md

+
+- All Exercism exercises must be defined in [problem-specifications](https://github.com/exercism/problem-specifications/tree/master/exercises) before they are implemented for a specific track. Please submit a PR there if your exercise is new to Exercism.
+
+- Please make sure the new exercise conforms to specifications in the [exercism/problem-specifications](https://github.com/exercism/problem-specifications) repo.  (Note if slight changes are needed for Rust


I would say / instead of \ in .meta\hints.md, for consistency with other instances of directory separator in this file (exercism/discussions, exercises/exercise/name, etc.)

petertseng · 2017-07-28T06:29:25Z

README.md

+  the differences required for Rust are explained.  If it a large change, you may want to call this out
+  as a comment at the top of `src/lib.rs`, so the user recognises to read this section before starting.
+
+- If an `example.rs` uses external crates, include `Cargo-example.toml` so that `_tests\check-exercises.sh` can compile with these when testing.


I would say / instead of \ in _test\check-exercises.sh, for consistency with other instances of directory separator in this file (exercism/discussions, exercises/exercise/name, etc.)

petertseng · 2017-07-28T06:29:46Z

README.md

+
+- An exercise may contain `.meta/hints.md`.  This is optional and will appear after the normal exercise
+  instructions if present.  Rust is different in many ways from other languages.  This is a place where 
+  the differences required for Rust are explained.  If it a large change, you may want to call this out


"If it a large change" - missing word

petertseng · 2017-07-28T06:30:34Z

README.md

+- We are currently committing Cargo.lock.  This may change.
+
+- `README.md` may be regenerated from exercism data.  The top section above `## Rust Installation` should contain `description.md` from the exercise directory in the 
+[problem-specifications github.](https://github.com/exercism/problem-specifications/tree/master/exercises)  The `## Source` section comes from the `metadata.yml` in the same directory.


I would say "problem-specifications repository" instead of "problem-specifications github" (since it may not always be clear what github means when used in that context)

petertseng · 2017-07-28T06:31:14Z

README.md

+
+- If an `example.rs` uses external crates, include `Cargo-example.toml` so that `_tests\check-exercises.sh` can compile with these when testing.
+
+- We are currently committing Cargo.lock.  This may change.


I am not convinced "This may change" is necessary, since ostensibly anything in this document could be subject to change. I would remove it

petertseng · 2017-07-28T06:33:58Z

README.md

+
+- Be sure to add the exercise to an appropriate place in the `config.json` file.  The position in the file determines the order exercises are sent.   Generate a unique UUID for the exercise.  Current difficuly levels in use are 1, 4, 7 and 10.
+
+- The Rust repository uses [Travis CI](https://travis-ci.org/exercism/rust/) to validate the build and automatically runs `bin/fetch-configlet && bin/configlet` to ensure the exercises are configured correctly.


Were I reading this sentence, I would ask the question "How does this affect me? Why did you tell me this?". Shall we put an answer to that after?

This also seems oddly placed since _test/check-exercises.sh is mentioned far above, and it kind of seems like they are related (both are run by Travis CI). Does it make sense to mention the two things closer together?

sacherjj · 2017-07-28T14:10:11Z

Addressed all comments.

Added section for version number in Cargo.toml based on canonical-data.json being present. Based on changes in one of my submitted exercises.

Moved Rust icon to bottom of the file as second change.

petertseng · 2017-07-31T07:51:08Z

An interesting thing happened since this PR was submitted: exercism/generic-track#37 was made in the request-new-language-track. Are any of those changes suitable to be included in this PR as well?

petertseng · 2017-09-20T02:21:11Z

well OK, in that case I'll just do whatever I think is right.

This reverts commit b78c8e0.

Before: https://github.com/exercism/request-new-language-track/blob/53b185fdc67f0e5e7bc2b0891c2a1cb30e4b5f05/README.md After: https://github.com/exercism/request-new-language-track/blob/master/TRACK_README.md (current sha is 907c3210b89bbc49c04ffa85f3b71f51cd9f8c1c) https://github.com/exercism/request-new-language-track/blob/907c3210b89bbc49c04ffa85f3b71f51cd9f8c1c/TRACK_README.md Closes #278

sacherjj changed the title ~~First pass at Main README.md #287~~ First pass at Main README.md - Issue #287 Jul 25, 2017

sacherjj changed the title ~~First pass at Main README.md - Issue #287~~ First pass at Main README.md - Issue #278 Jul 25, 2017

petertseng reviewed Jul 25, 2017

View reviewed changes

sacherjj force-pushed the main_readme branch from 64a971d to bfcd581 Compare July 26, 2017 01:33

petertseng reviewed Jul 28, 2017

View reviewed changes

sacherjj force-pushed the main_readme branch from bfcd581 to 66cc5a3 Compare July 28, 2017 14:06

First pass at Main README.md exercism#287

a47baaf

sacherjj force-pushed the main_readme branch from 66cc5a3 to a47baaf Compare July 28, 2017 14:09

petertseng added 7 commits September 19, 2017 19:22

rust icon to bottom

110b91a

deduplicate contributing

7112243

standards are in the docs repo

3b0aa57

remove trailing ## (they don't hurt, but aren't needed)

f765892

tests -> docs

72062f6

pull request -> opening issue, verifying change

c285df9

new exercise

19b931a

petertseng force-pushed the main_readme branch from 76504fd to 19b931a Compare September 20, 2017 02:33

petertseng added 9 commits September 19, 2017 19:33

trailing space

67662c2

submit: not a bullet point

38f53b3

README generation: make link and also link to rust insert

8bcfc90

publishing -> porting, say version IN canonical-data

2b770f1

I don't think we want these horizontal rules

68f0f3a

huh ok, so let's have backticks instead

b78c8e0

Revert "huh ok, so let's have backticks instead"

fafa603

This reverts commit b78c8e0.

indenting it more will work

9eccb87

combine guidance about external creates into one bullet point

f93600d

petertseng merged commit 9af9dc3 into exercism:master Sep 20, 2017

sacherjj deleted the main_readme branch September 20, 2017 12:23

petertseng mentioned this pull request Sep 22, 2017

Document why we ignore all tests but the first #279

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

First pass at Main README.md - Issue #278 #334

First pass at Main README.md - Issue #278 #334

sacherjj commented Jul 25, 2017

petertseng left a comment

petertseng Jul 25, 2017

petertseng Jul 25, 2017

petertseng Jul 25, 2017 •

edited

Loading

sacherjj commented Jul 26, 2017

petertseng left a comment

petertseng Jul 28, 2017 •

edited

Loading

petertseng Jul 28, 2017

petertseng Jul 28, 2017

petertseng Jul 28, 2017

petertseng Jul 28, 2017

petertseng Jul 28, 2017

petertseng Jul 28, 2017

petertseng Jul 28, 2017

sacherjj commented Jul 28, 2017

petertseng commented Jul 31, 2017

petertseng commented Sep 20, 2017


		- Be sure to add it to the appropriate place in the `config.json` file. Position in the file determines the order exercises are sent. Generate a unique UUID for the exercise. Current difficuly levels in use are 1, 4, 7 and 10.

		- !!!!! Not sure if this is accurate !!!!! Also, please run `bin/fetch-configlet && bin/configlet` to ensure the exercise is configured correctly.


		- Exercises should use only the Rust core libraries. If you must use an external crate, see note below about `Cargo-example.toml`. `Cargo.toml` should not have external dependencies as we don't want to make the user assume which crates are required.

		- !!!!! Not sure if this is accurate !!!!! Please do not add a README or README.md file to the exercise directory. The READMEs are constructed using shared metadata, which lives in the


		## Contributing a New Exercise ##

		- All Exercism exercises must be defined in [problem-specifications](https://github.com/exercism/problem-specifications/tree/master/exercises) before they are implemented for a specific track. Please submit a PR there if your exercise is new to Exercism.


		- Watch out for trailing spaces, extra blank lines, and spaces in blank lines.

		- All the tests for Rust exercises can be run from the top level of the repo with `_test\check-exercises.sh` Please run this command before submitting your PR. See [Windows Specific instructions](_test/WINDOWS_README.md) for running this.


		- All Exercism exercises must be defined in [problem-specifications](https://github.com/exercism/problem-specifications/tree/master/exercises) before they are implemented for a specific track. Please submit a PR there if your exercise is new to Exercism.

		- Please make sure the new exercise conforms to specifications in the [exercism/problem-specifications](https://github.com/exercism/problem-specifications) repo. (Note if slight changes are needed for Rust


		- If an `example.rs` uses external crates, include `Cargo-example.toml` so that `_tests\check-exercises.sh` can compile with these when testing.

		- We are currently committing Cargo.lock. This may change.


		- Be sure to add the exercise to an appropriate place in the `config.json` file. The position in the file determines the order exercises are sent. Generate a unique UUID for the exercise. Current difficuly levels in use are 1, 4, 7 and 10.

		- The Rust repository uses [Travis CI](https://travis-ci.org/exercism/rust/) to validate the build and automatically runs `bin/fetch-configlet && bin/configlet` to ensure the exercises are configured correctly.

First pass at Main README.md - Issue #278 #334

First pass at Main README.md - Issue #278 #334

Conversation

sacherjj commented Jul 25, 2017

petertseng left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

petertseng Jul 25, 2017 • edited Loading

Choose a reason for hiding this comment

sacherjj commented Jul 26, 2017

petertseng left a comment

Choose a reason for hiding this comment

petertseng Jul 28, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sacherjj commented Jul 28, 2017

petertseng commented Jul 31, 2017

petertseng commented Sep 20, 2017

petertseng Jul 25, 2017 •

edited

Loading

petertseng Jul 28, 2017 •

edited

Loading