From e2abba77cb5a395702f237e428b639f2129b1f07 Mon Sep 17 00:00:00 2001 From: Barry Moore <3086255+chiroptical@users.noreply.github.com> Date: Wed, 12 Jun 2024 11:46:09 -0400 Subject: [PATCH] Add a CONTRIBUTING.md to clarify project structure and valid contributions (#550) * Add a recommended project stucture * Add description for languages with more than one unit testing framework --- .github/pull_request_template.md | 1 + CONTRIBUTING.md | 44 ++++++++++++++++++++++++++++++++ README.md | 20 +++------------ 3 files changed, 49 insertions(+), 16 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 76d0e96c..8de2ef94 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -3,5 +3,6 @@ Please do not submit a PR with your solution to the Gilded Rose Kata. This repo is intended to be used as a starting point for the kata. - [ ] I acknowledge that this PR is not a solution to the Gilded Rose Kata, but an improvement to the template. +- [ ] I acknowledge that I have read [CONTRIBUTING.md](https://github.com/emilybache/GildedRose-Refactoring-Kata/blob/main/CONTRIBUTING.md) ## Please provide your PR description below this line diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..c8a521af --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,44 @@ +Contributing to Gilded Rose Refactoring Kata +====== + +More translations are most welcome! I'm very open for pull requests that +translate the starting position into additional languages. However, please +do **not** open a pull request with your solution! It can be a bit confusing since +GitHub encourages you to do so! Please only send me pull requests if you have a +correction or improvement to the starting position. You don't want to spoil the +fun of doing the exercise for other people! + +# Translating this code + +Please note a translation should ideally include: + +- a translation of the production code for 'update_quality' and Item +- one failing unit test complaining that "fixme" != "foo" +- a TextTest fixture, i.e. a command-line program that runs update_quality on the sample data for the number of days specified + +Please don't write too much code in the starting position or add too many unit +tests. The idea with the one failing unit test is to tempt people to work out +how to fix it, discover it wasn't that hard, and now they understand what this +test is doing they realize they can improve it. + +If your programming language doesn't have an easy way to add a command-line +interface, then the TextTest fixture is probably not necessary. + +# Recommended project structure + +Programming languages have a variety of conventions but the starting points try +to maintain order among languages. Ideally, the 'update_quality' and +Item definitions should be in a file named `gilded_rose` with your language's +conventional casing (e.g. snake case) and location (e.g. `src/`). The "fixme" ! += "foo" test should go in a file `gilded_rose_test` in your language's +conventional location (e.g. `test/`). The TextTest fixture and command-line +program, that simulates update_quality over a number of days, should go in +`program` or `texttest_fixture`. If you can define a default for the number of +days in the simulation please choose two days. + +A single sub-directory per language is not enforced. A language may have +more than one popular unit testing framework. In that case, please add +`{language}-{framework}/` and maintain separation between the projects. In other +words, all the components requested should exist in both sub-directories. +Re-using code between the directories would be confusing for those looking for a +starting point. diff --git a/README.md b/README.md index d71b9deb..4984887d 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,6 @@ Alternatively, use the Approval tests provided in this repository. (Read more ab The idea of the exercise is to do some deliberate practice, and improve your skills at designing test cases and refactoring. The idea is not to re-write the code from scratch, but rather to practice taking small steps, running the tests often, and incrementally improving the design. -Please don't send me a pull request with your solution. It can be a bit confusing since GitHub encourages you to do so! Please only send me pull requests if you have a correction or improvement to the starting position. You don't want to spoil the fun of doing the exercise for other people! - - ### Gilded Rose Requirements in other languages - [English](GildedRoseRequirements.md) @@ -49,17 +46,8 @@ As Bobby Johnson points out in his article ["Why Most Solutions to Gilded Rose M better practice at handling a legacy code situation if you do this Kata in the original C#. However, I think this kata is also really useful for practicing writing good tests using different frameworks and approaches, and the small changes I've made help with that. I think it's also interesting to compare what the refactored code and tests look like in different programming languages. -## Translating this code - -More translations are most welcome! I'm very open for pull requests that translate the starting position into additional languages. - -Please note a translation should ideally include: - -- a translation of the production code for 'update_quality' and Item -- one failing unit test complaining that "fixme" != "foo" -- a TextTest fixture, ie a command-line program that runs update_quality on the sample data for the number of days specified. - -Please don't write too much code in the starting position or add too many unit tests. The idea with the one failing unit test is to tempt people to work out how to fix it, discover it wasn't that hard, and now they understand what this test is doing they realize they can improve it. - -If your programming language doesn't have an easy way to add a command-line interface, then the TextTest fixture is probably not necessary. +## Contributing +Contributions are encouraged! You could add a translations of the specification +in another language or a new starting point for your favorite programming +language. Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for more details.