diff --git a/infra/GutUsageExamples.md b/infra/GutUsageExamples.md index 4d715443..a8b579b5 100644 --- a/infra/GutUsageExamples.md +++ b/infra/GutUsageExamples.md @@ -1,12 +1,37 @@ -# Task 1: add a new language +# Task 1: Initialise `gut` + +To set up `gut` for the first time, with `giellalt` as your default organisation (so you don't have to specify it for every `gut` operation, do as follows (remember to have your GitHub Peronal access token available): + +```sh +gut init --root /path/to/your/gut/root/dir --token PERSONALACCESSTOKEN \ + --organisation giellalt --use-https +``` + +Using `https` has proven to be the most stable, but feel free to skip that part, and use the `git` protocol instead. + +# Task 2: Clone multiple repos in one go + +The very basic task of getting started: + +```sh +gut clone -o giellalt -r ^lang +``` + +This will clone all repos in the `giellalt` org matching the regular expression `^lang` in the repo name. Use option `-u` to clone using the `https` protocol instead of `ssh`: + +```sh +gut clone -u -o giellalt -r ^lang +``` + +# Task 3: add a new language Description moved to a [separate page](HowToAddANewLanguage.md). -# Task 2: update template, propagate changes to all matching repos +# Task 4: update template, propagate changes to all matching repos Description moved to a [separate page](infraremake/HowToMergeUpdatesFromCore.md). -# Task 3: manage topics, info +# Task 5: manage topics, info ## Set topics @@ -28,13 +53,13 @@ gut topic add -o giellalt -r "lang-(s|cr)" -t indigenous-languages gut set info -o giellalt -r "(lang-|giella-)" -w https://giellalt.uit.no ``` -# Task 4: make repo(s) public/private +# Task 6: make repo(s) public/private ```sh gut make -o giellalt -r "(lang-|giella-)" private ``` -# Task 5: add description with dynamic content +# Task 7: add description with dynamic content ```sh gut set info -o giellalt -r 'lang-XXX' --des-script giella-core/devtools/gut-scripts/reponame2description.sh @@ -42,20 +67,20 @@ gut set info -o giellalt -r 'lang-XXX' --des-script giella-core/devtools/gut-scr **NB!** Make sure there is no trailing newline at the end of the output of the script, or it will fail. That is, use `printf`, *not* `echo`. -# Task 6: create team, and populate with users +# Task 8: create team, and populate with users ```sh gut create team -o giellalt -t "Kainun kieli" \ -d "Team for working with the kveen language." -m Trondtr snomos ``` -# Task 7: add users to an existing team +# Task 9: add users to an existing team ```sh gut add users -o giellalt -t giellaltstaff -u ilm024 leneantonsen ``` -# Task 8: add webhook +# Task 10: add webhook ```sh gut hook create -m json -o giellalt -r 'lang-' \ @@ -98,7 +123,7 @@ gut hook create -m json -o giellalt -r 'lang-' \ More information about the various webhook events can be found in the [GitHub Documentation](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/webhook-events-and-payloads). -# Task 9: add external repo using `git subtree` +# Task 11: add external repo using `git subtree` There are a lot of FST descriptions of languages out there, one major such source is [Apertium](https://github.com/apertium). But most of these projects do not make spelling checkers or many other tools based on their morphological description. Since we have the infrastructure and the tools in place to make all languages work, it might be useful to just take those repos, and compile their fst within our infra, and from there make spellers, tokenisers, and a lot of other stuff. To do that, add a new language as follows: @@ -116,21 +141,7 @@ When you later want to update the code from the external repository, do as follo git subtree pull --prefix src/fst/ext-Apertium-nno https://github.com/apertium/apertium-nno.git master --squash ``` -# Task 10: Clone multiple repos in one go - -The very basic task of getting started: - -```sh -gut clone -o giellalt -r ^lang -``` - -This will clone all repos in the `giellalt` org matching the regular expression `^lang` in the repo name. Use option `-u` to clone using the `https` protocol instead of `ssh`: - -```sh -gut clone -u -o giellalt -r ^lang -``` - -# Task 11: Set team access permission +# Task 12: Set team access permission NB! Requires owner permission by the user doing this!