Skip to content

Conversation

@cmccandless
Copy link
Contributor

No description provided.

@cmccandless cmccandless requested a review from kytrinyx August 7, 2019 16:24
@cmccandless cmccandless requested a review from a team as a code owner August 7, 2019 16:24
@cmccandless cmccandless changed the title Docs contributing and generator Add track Contributing Guide and Generator documentation Aug 7, 2019
Copy link
Member

@kytrinyx kytrinyx left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great. I can't speak to the python-specifics, but it is lovely to see thorough documentation.

Copy link
Contributor

@yawpitch yawpitch left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Excellent work ... only thing I'd think about changing is maybe replacing "fake_exercise" with something like "[EXERCISE]", and slightly re-arranging the order of the extra files to keep them related to the order of the files they modify.

exercises/[EXERCISE]/
├── [EXERCISE].py
├── [EXERCISE]_test.py
├── example.py
├── .meta
│   ├── template.j2
│   ├── additional_tests.json
│   └── hints.md
└── README.md

Plus updating the table to reflect and be a little bit more explicit:

  • fake_exercise.py Solution stub manually created by the implementer. (See exercises/hello-world/hello_world.py)
  • fake_exercise_test.py Exercise test suite; automatically generated if .meta/template.j2 is present, otherwise manually created by the implementer. (See exercises/hello-world/hello_world_test.py)
  • example.py Example solution manually created by the implementer and used to automatically verify the [EXERCISE]_test.py suite. (See exercises/hello-world/example.py)
  • .meta/template.j2 Test generation template; if present used to automatically generate [EXERCISE]_test.py. (See exercises/hello-world/.meta/template.j2)
  • .meta/additional_tests.json Defines additional track-specific test cases; if .meta/template.j2 is also present these tests will be incorporated into the automatically generated [EXERCISE]_test.py. (See exercises/word-count/.meta/additional_tests.json)
  • .meta/hints.md Contains track-specific hints that are automatically included in the generated README.md file. (See exercises/high-scores/.meta/hints.md)
  • README.md Exercise README automatically generated by the configlet tool. (See exercises/hello-world/hello_world.py)

I'd think grouping them together buy functionality makes the whole easier to understand than lexical ordering as they'd get from tree.

That said I'd still merge it as is if you don't agree.

cmccandless and others added 2 commits August 8, 2019 11:43
Suggestions: exercism#1900 (review)

Co-authored-by: Michael Morehouse <640167+yawpitch@users.noreply.github.com>
@cmccandless
Copy link
Contributor Author

maybe replacing "fake_exercise" with something like "[EXERCISE]", and slightly re-arranging the order of the extra files to keep them related to the order of the files they modify.

Initially I had example_exercise, but that looked confusing with example_exercise.py and example.py. I like your idea better.

Copy link
Contributor

@yawpitch yawpitch left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes look great!

@yawpitch yawpitch merged commit dd698d1 into exercism:master Aug 8, 2019
@cmccandless cmccandless deleted the docs-contributing-and-generator branch August 8, 2019 16:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants