From e9d3cfe4055771ba8bd0740dfbbf718152f8bf01 Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Tue, 31 Aug 2021 17:28:35 -0400 Subject: [PATCH] Refresh track docs --- CONTRIBUTING.md | 312 +-------------------------------- POLICIES.md | 12 +- _template/README.md | 9 + docs/INSTALLATION.md | 2 +- docs/LEARNING.md | 26 ++- docs/MAINTAINING.md | 4 +- docs/RESOURCES.md | 5 +- docs/TESTS.md | 30 ++-- exercises/shared/.docs/help.md | 4 +- 9 files changed, 59 insertions(+), 345 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 012b378b..0e8f9750 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,312 +1,14 @@ # Contributing to the Bash Track +Please see the central Exercism contributing documents: + +* [Being a Good Exercism Community Member](https://github.com/exercism/docs/tree/main/community/good-member#being-a-good-exercism-community-member) +* [Community](https://github.com/exercism/docs/tree/main/community) +* [Contributing to Exercism](https://github.com/exercism/docs/tree/main/building) +* [Building / Tracks](https://github.com/exercism/docs/tree/main/building/tracks) + There are a lot of great resources for contributing to Exercism in general already. Check out the [docs] repository for a larger overview and some more general purpose instructions. [docs]: (https://github.com/exercism/docs) - -Make sure you read the [policies document] and follow the conventions we agreed upon. - -[policies document]: (https://github.com/exercism/bash/blob/master/docs/POLICIES.md) - -A great way to get started contributing is [porting an exercise] from another -track! It helps you get into the repository, learn your way around, and see -how things are structured. - -[porting an exercise]: (#porting-an-exercise-from-another-language) - -## Getting Set Up - -In order to run any of the test files (or examples, for that matter), you're -going to need Bash. If you're on OSX or Linux, this shouldn't be a problem for -you. Additionally, you'll need the Bash test runner that we're using: `bats`. -This can be installed via your package manager. For more specifics, see the -[tests page] of this repositorys docs. - -[tests page]: https://github.com/exercism/bash/blob/master/docs/TESTS.md - -## Porting an Exercise from Another Language - -Porting an exercise from another language is easy (ish)! [Problem -specifications] for [unimplemented exercises] can be used to do this. - -[Problem specifications]: www.github.com/exercism/problem-specifications -[unimplemented exercises]: www.exercism.io/languages/bash/todo - -The `_template` directory found in `exercism/bash` can be used to port -exercises. Once an example submission, full test suite and README.md have been -created, you just need to alter `config.json` to include the newly implemented -exercise. - -### Initial Setup - -Fork the Bash repository on GitHub (which you are currently in). - -![Fork button](img/fork-repository.png) - -Clone the repository to your computer. - -```bash -$ git clone https://github.com//bash.git -$ cd bash -``` - -Look through the [list of exercises not yet implemented] in Bash. Once you've -found one you like, make sure that someone's not already working on it by -checking the [current open pull requests]. Also double check that the exercise -isn't in the list of exercises already implemented in your freshly cloned -repository: `path/to/bash/exercises`. Once you've selected an exercise you -like, locate its *slug* (unique name) in the [master list] of problem -specifications. - -[list of exercises not yet implemented]: http://exercism.io/languages/bash/todo -[current open pull requests]: https://github.com/exercism/bash/pulls -[master list]: https://github.com/exercism/problem-specifications/tree/master/exercises - -Create a directory in your local `exercises` folder with that same slug name. - -```bash -# Optionally, but probably a good idea, create a new branch for your exercise -$ git checkout -b -# Create the new exercise directory -$ mkdir exercises/ -``` - -At the very least, you're going to need to create a `README.md`, a test file -(`your_exercise_test.sh`), and an example file which, by convention, you should -name `example.sh` when you're done. For ease of debugging, you can start by -naming your file `your_exercise.sh`. - -```bash -$ touch README.md -$ touch _test.sh -$ touch .sh -``` - -Ensure that both of the shell script files are executeable. - -```bash -$ chmod a+x _test.sh .sh -``` - -Many, if not all, of the current exercises have *canonical data* about them -that is the same accross all languages. This makes it so you don't have to -come up with test cases or informative intro material yourself. You're -welcome! Head over to your specific exercise page in the [master list] (same -link as above). Specifically right now, you're interested in -`canonical_data.json`. - -![Canonical data example](img/canonical-data-example.png) - -Currently, you're interested in all of the `"cases"`. Each of these is a test -case that you'll have to implement in the specific vernacular of our -test-runner, `bats`. Check out this repository's [test documentation] if you -missed the [Getting Set Up] section above. - -[test documentation]: https://github.com/exercism/bash/blob/master/docs/TESTS.md -[Getting Set Up]: #getting-set-up - -### Generating the Tests - -Implement each of the test cases (along with any comments or explanations you -think are necessary for people who aren't sure of themselves). When in doubt, -check out the other, already implemented exercises for an example. Here's an -example of implementing the test case shown above. - -```bash -#!/usr/bin/env bats - -@test 'Say Hi!' { - run bash hello_world.sh - [ "$status" -eq 0 ] - [ "$output" = "Hello, World" ] -} - -# ... The rest of your tests -``` - -For each test you create, you should use the `description` value for the test -case description. The `property` value is generally used by other languages to -specify what the function to be run is called. Use your best judgement and -check out how other exercises handle this. If there's just one property, you -can just test the script as a whole. If there's multiple properties, consider -testing those as either subcommands or flags (e.g. an exercise with an encode -and a decode property could be handled by `run bash cyper.sh encode ` -or by `run bash cypher.sh -e `). You're the one writing the tests, -so you decide. You'll get feedback when you open your pull request anyways, so -don't stress too much about it. - -For test cases that are expected to return `true` or `false` make sure you are -expecting an output value. It is better to return `"true"` or `true`, to the -console instead of just relying on the exit status in bash (0 for success, -1-255 for error). This will be consistent with the existing exercises and -prevent possible issues in the future. - -You can check to see if your example script works by running `bats`. - -```bash -$ bats hello_world_test.sh -``` -#### Automatic test generator - -**Tired of reading JSON by hand everytime an exercise version is updated?** - -There is a Ruby and ERB based automated solution for generating tests -at [guygastineau/bash-track-test-generator](https://github.com/guygastineau/bash-track-test-generator). - -This tool automatically rewrites the test for an exercise to keep it -up to date with the `canonical-data.json` file for the exercise in -`exercism/problem-spcifications`. - -For more information on using this tool please see the README.md [here](https://github.com/guygastineau/bash-track-test-generator/blob/master/README.md). - -### Implementing an Example Solution - -If you've been following along so far, your tests should fail. Go ahead and -implement your solution in the `.sh` file. Make sure your file -has `#!/usr/bin/env bash` ([shebang]) at the top. - -[shebang]: https://en.wikipedia.org/wiki/Shebang_(Unix) - -Keep running your test file against it until your tests all pass. This process -should help ensure that both your tests *and* your example are ship shape! - -Once your tests and example are complete, rename `.sh` to -`example.sh` to match all the other exercises. - -### Updating the Config - -Exercism makes heavy use of configuration files to automate things. Now that -you're done with your solution, you can add your problem to -`bash/config.json`. Check out the [configuration description] in the Exercism -docs for more info on each item. - -[configuration description]: https://github.com/exercism/docs/blob/master/language-tracks/configuration/exercises.md - -```javascript -// config.json -{ - "exercises": [ - // ... All the other exercises - { - "core": false, // True or false, you decide - "unlocked_by": "leap", // If core is false, pick a core exercise that - // unlocks this one. Something similar, but easier - "difficulty": 1, // 1 == easy, 10 == impossible, you decide - "slug": "", - "topics": [ - "control_flow_conditionals", - "mathematics" // These can come from the topics list, linked below - ], - "uuid": "9ac0b041-a7aa-4b0c-952a-d38d35e2cd65" // see below - } - ] -} -``` - -Possible topics that describe your exercise can come from the [topics master -list], but you're not limited to those. - -[topics master list]: https://github.com/exercism/problem-specifications/blob/master/TOPICS.txt - -In order to get the `uuid` and check your work, you'll need the configlet, -which is a handy tool created to automate some of the more monotonous tasks -involved with this. See the [configlet documentation] for more info. Make -sure you have the most current configlet by running: - -[configlet documentation]: (https://github.com/exercism/configlet) - -```bash -$ bin/fetch-configlet -``` - -Each exercise *for each language* needs a unique ID number — a `uuid`. The -configlet can help you generate one. - -```bash -$ bin/configlet uuid -``` - -Copy/paste the generated value into the `uuid` field of your exercise. Once -you're done, it's time to check your work. Run the configlet linter. - -```bash -$ bin/configlet lint . -# If for some reason you're not inside the project directory, instead use -$ bin/configlet lint path/to/bash -``` - -Hopefully it says everything is OK! - -### Creating the README - -There are two ways to create the README: generate it via the configlet, or -manually create it. This guide covers them both. - -#### Using the Configlet - -The configlet has a generate command that uses Go templating and pulls from the -repository's `config` directory as well as each exercise's `.meta` directory. -For example, any necessary `hints.md` should be put in `.meta` so configlet may -pull it in. Learn more in the [configlet docs]. You should just be able to run: - -[configlet docs]: https://github.com/exercism/configlet - -```bash -$ bin/configlet generate -``` - -This should auto-generate a nice README in your exercise directory. If it -gives you any issues, no worries! You can always get it done by... - -#### Doing It Manually - -Use the `config/exercise_readme.go.tmpl` file as a guide. The README should -look something like this: - -```markdown -# - -... Description copied from the master exercise repo (where you got your tests) - -... Any additional hints that need provided - -... Bash standard material, copied from `docs/EXERCISE_README_INSERT.md` - -## Source - -... Copy credits from the master exercise repo - -## Submitting Incomplete Solutions - -It's possible to submit an incomplete solution so you can see how others have -completed the exercise. -``` - -### Cleaning Up - -If you've been practicing good version control throughout this process, you may -have several commits. At this point, you're almost ready to submit your pull -request, but you should rebase against the most recent upstream master branch. - -```bash -# Assuming you've already 'git added' and 'git commited' -# If you don't already have the exercism/bash as your upstream remote: -$ git remote add upstream https://github.com/exercism/bash.git -# To get the most recent upstream version -$ git fetch upstream -# Rebase onto the upstream -$ git rebase upstream/master -``` - -Now you're ready to sync up with Github and open your pull request! - -```bash -$ git push origin -``` - -![Create pull request](img/create-pr.png) - -Good luck, happy scripting, and thanks for your help! - diff --git a/POLICIES.md b/POLICIES.md index 05a1ee32..f5f7c154 100644 --- a/POLICIES.md +++ b/POLICIES.md @@ -36,18 +36,12 @@ References: [[1](https://github.com/exercism/bash/issues/88)] ### Exercise structure -For an exercise "exercise", you should provide the following files: - -- `README.md`, which describes the exercise -- `exercise_test.sh`, which contains the tests for the implementation -- `example.sh`, an example implementation that passes the tests -- `.meta/version`, which contains the exercise version from `https://github.com/exercism/problem-specifications/exercises/exercise/canonical-data.json` - -References: [[1](https://github.com/exercism/bash/issues/87#event-1446351332)] +Please see the [Practice Exercises](https://github.com/exercism/docs/blob/main/building/tracks/practice-exercises.md) +document, which thoroughly discusses the structure of an exercise. ### Exercise Test Structure -The tests will not enforce using a specific function, unless the problems are complex or requires it (ex: https://github.com/exercism/bash/blob/master/exercises/triangle/triangle_test.sh) +The tests will not enforce using a specific function, unless the problems are complex or requires it (ex: https://github.com/exercism/bash/blob/main/exercises/practice/list-ops/list_ops_test.sh) ``` run bash exercise.sh "string" diff --git a/_template/README.md b/_template/README.md index ff058397..8be983ef 100644 --- a/_template/README.md +++ b/_template/README.md @@ -1,5 +1,12 @@ # README +**_TODO: this needs to be rewritten for exercism v3_** + +In [my](https://github.com/glennj) experience, the simplest way to create a new exercise is to +(recursively) copy an existing exercise and systematically update each file. + + diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index 9d7c12e3..5f2e3bd8 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -39,7 +39,7 @@ There is NO WARRANTY, to the extent permitted by law. ``` If it does not, you may not have bash installed. -You should install it using your distributions package manager. +You should install it using your distribution's package manager. ## Windows diff --git a/docs/LEARNING.md b/docs/LEARNING.md index b54d5379..a54d00e8 100644 --- a/docs/LEARNING.md +++ b/docs/LEARNING.md @@ -1,10 +1,20 @@ # Learning -Bash is a very powerful Unix shell and command scripting language. -The man page for Bash is a well written and informational document. -Additional guides, information, and examples can be found at -[Greg's Wiki](http://mywiki.wooledge.org/BashGuide) and the -[GNU Bash Manual](http://gnu.org/s/bash/manual). -[shellcheck.net](https://www.shellcheck.net/) provides a web interface -(and binary for some distros) that checks shell scripts for errors or -common issues and provides information on how to best correct them. +Bash is a very powerful Unix shell and command scripting language, but it +does have a fairly steep learning curve. + +* The [man page](https://manpage.me/index.cgi?apropos=0&q=bash&sektion=1&manpath=Debian+7.8.0&arch=default&format=html) + for Bash is a well written and informational document. It is very "dense" + though, and requires reading and re-reading. + +* Additional guides, information, and examples can be found at + * [Greg's Wiki](http://mywiki.wooledge.org/BashGuide), + * the [Bash Hackers Wiki](https://wiki.bash-hackers.org), + * the [bash tag info page](https://stackoverflow.com/tags/bash/info) on + Stack Overflow, + * and expanding on the man page, the [GNU Bash Manual](http://gnu.org/s/bash/manual) + is _the_ source of information for bash. + +* [shellcheck.net](https://www.shellcheck.net/) provides a web interface + (and binary for some distros) that checks shell scripts for errors or + common issues and provides information on how to best correct them. diff --git a/docs/MAINTAINING.md b/docs/MAINTAINING.md index 8852f873..307a51b5 100644 --- a/docs/MAINTAINING.md +++ b/docs/MAINTAINING.md @@ -23,9 +23,7 @@ As a maintainer, you have write access to several repositories. "write access" ## Maintainer Guides -- **[docs/maintaining-a-track/README.md](https://github.com/exercism/docs/blob/master/maintaining-a-track/README.md)** -- [docs/contributing-to-language-tracks/README.md](https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/README.md) -- [docs/you-can-help/review-pull-requests.md](https://github.com/exercism/docs/blob/master/you-can-help/review-pull-requests.md) +- **[Maintainers](https://github.com/exercism/docs/blob/main/community/maintainers.md)** ## Miscellaneous diff --git a/docs/RESOURCES.md b/docs/RESOURCES.md index 6eb07aa4..47dfd1d7 100644 --- a/docs/RESOURCES.md +++ b/docs/RESOURCES.md @@ -5,7 +5,8 @@ - [Bash FAQ](http://mywiki.wooledge.org/BashFAQ) - [Bash Pitfalls](https://mywiki.wooledge.org/BashPitfalls) - [GNU Bash Manual](http://gnu.org/s/bash/manual) -- [Bash-Hackers Wiki](http://wiki.bash-hackers.org/) +- [Bash-Hackers Wiki](http://wiki.bash-hackers.org) - [Shellcheck provides shell script guidelines and help](http://www.shellcheck.net/) -The Command Line Heroes podcast released an episode on the [history of bash](https://www.redhat.com/en/command-line-heroes/season-3/heroes-in-a-bash-shell) +The Command Line Heroes podcast released an episode on the +[history of bash](https://www.redhat.com/en/command-line-heroes/season-3/heroes-in-a-bash-shell) diff --git a/docs/TESTS.md b/docs/TESTS.md index 863f2d09..b15680f0 100644 --- a/docs/TESTS.md +++ b/docs/TESTS.md @@ -10,19 +10,7 @@ cd /path/to/your/exercise_workspace/bash/whatever bats whatever_test.sh ``` -## Legacy `bats` - -`bats-core` was forked from [the original `bats` -implementation](https://github.com/sstephenson/bats). The sstephenson/bats -was quite buggy and had been abandoned. Ownership was handed over in 2017: -[sstephenson/bats#150 (comment)](https://github.com/sstephenson/bats/issues/150#issuecomment-323845404) - -If you have the original sstephenson/bats installed (check with `bats -v` -reporting a version number less than 1.0), then you should switch to -bats-core: otherwise you may find yourself [experiencing unexplained test -failures](https://github.com/exercism/bash/pull/445). - -## Installing `bats` +## Installing `bats-core` You should be able to install it from your favorite package manager: @@ -38,8 +26,8 @@ $ brew install bats-core 🍺 /usr/local/Cellar/bats-core/1.1.0: 13 files, 55KB, built in 4 seconds ``` -* The legacy `bats` package also exists in the homebrew ecosystem. Do not -install that by mistake, install `bats-core`. +* The legacy `bats` package also exists in the homebrew ecosystem. _Do not +install that by mistake_: install `bats-core`. ### For Linux @@ -80,3 +68,15 @@ There are reports that [newer bats versions don't behave well on MinGW bash](htt ``` $ git checkout v1.1.0 ``` + +## Legacy `bats` + +`bats-core` was forked from [the original `bats` +implementation](https://github.com/sstephenson/bats). The sstephenson/bats +was quite buggy and had been abandoned. Ownership was handed over in 2017: +[sstephenson/bats#150 (comment)](https://github.com/sstephenson/bats/issues/150#issuecomment-323845404) + +If you have the original sstephenson/bats installed (check with `bats -v` +reporting a version number less than 1.0), then you should switch to +bats-core: otherwise you may find yourself [experiencing unexplained test +failures](https://github.com/exercism/bash/pull/445). diff --git a/exercises/shared/.docs/help.md b/exercises/shared/.docs/help.md index 9591180c..681723e6 100644 --- a/exercises/shared/.docs/help.md +++ b/exercises/shared/.docs/help.md @@ -27,5 +27,5 @@ the exercise. For an extra challenge, if you would like to have a better understanding of the language, try to re-implement the solution in pure bash, without using any external tools. There are some types of problems that bash cannot solve, -such as performing floating point arithmetic and manipulating dates: for -those, you must call out to an external tool. +such as floating point arithmetic and manipulating dates: for those, you +must call out to an external tool.