From b96fee2e054814e937967782d7842f48d9d38de4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Fri, 24 Feb 2023 16:57:44 +0100 Subject: [PATCH 01/15] Automatically generate contracts documentation We are creating a GH Actions workflow which automatically generates the contracts documentation in Markdown, based on the functions and the NatSpec-format comments in the Solidity files stored in the `contracts` folder in `keep-network/tbtc-v2/solidity`. For certain workflow triggers, the generated documentation will be pushed to the `threshold-network/threshold` repository, under `./docs/app-development/tbtc-v2/tbtc-v2-api`. As the `.docs` folder is synched with Threshold docs GitBook space, the pushed docs will be displayed in HTML under `docs.threshold.network` domain. There are two main jobs in the workflow: * `contracts-docs-publish-preview` * `contracts-docs-publish` Both call a reusable workflow `reusable-solidity-docs.yml` which resides in the `keep-network/ci` repository under `.github/workflows`. The jobs differ in parameters with witch the reusable action is called. The common part of the jobs is the beginning stage, where the Solidity files are being prepared for Markdown generation. During that stage the jobs will remove the spaces chars between the NatSpec comments markers (`///`) and the text of the comment. This is done to ensure proper rendering of the lists in the output docs and is a default action made by `reusable-solidity-docs.yml`. Another pre-processing is running a `sed` command on a `./contracts/bridge/BitcoinTx.sol` that removes incorrectly used line with `//` blank comment in the middle of section with NatSpec's `///` comments (which was breaking the formatting of that comment in Markdown). Once files are ready, the jobs use Docgen tool to generate the Markdown docs. The tool needs to be installed in the project and configured in the `hardhat.config.ts`. The configuration that we use specifies that the docs should be generated to the `geerated-docs` subfolder, to one single `index.md` file. The `.sol` files in the `./solidity/contracts/test` folder will be ignored during generation (those are test/stub contracts which are not used on Mainnet). A custom template will be used during docs generations. The template was created based on the default `https://github.com/OpenZeppelin/solidity-docgen/blob/master/src/themes/markdown/common.hbs` template, but it removes the cursive from the `@dev` type comments (because the cursive didn't work well with formatting of the lists). Once the Docgen is run and the `index.md` file is generated, the jobs will add a Table of Contents to the file, to improve the navigation. The TOC will be added by the `markdown-toc` tool and will be generated using `--maxdepth 2` param, which results in listing all the contract names, but not the functions. Once the TOC is added, we'll start to see the difference in the behavior of the jobs. The `contracts-docs-publish-preview` job is triggered for: * `pull_request` events, if the PR modifies either files if `./solidity/contracts` or the workflow file itself, * `push` events, when the push is made to a branch which name starts with `releases/mainnet/solidity/`, * `workflow_dispatch` events. The job publishes the generated artifacts as artifacts of the GH Actions workflow run. For PRs, link to the run with the artifacts will be posted as a PR comment. The `contracts-docs-publish` job is triggered for: * published releases, which names start with `refs/tags/solidity/`. The job pushes the generated file to the `./docs/app-development/tbtc-v2/tbtc-v2-api` folder in the `threshold-network/threshold` repo, to the `main` branch. The `.docs` folder is synched with the GitBook Threshold documentation, so thanks to the job, the changes in the contracts should be reflected on the docs.threshold.network. In order for the job to work, we need to configure a user which will create the commit The user needs to have right to commit to the `threshold-network/threshold` repo. We also need to configure following secrets: - [ ] `THRESHOLD_DOCS_GITHUB_TOKEN` - [ ] `GPG_PRIVATE_KEY` - [ ] `GPG_PASSPHRASE` We're using a GPG key to be able to do verified commits. --- .github/workflows/contracts-docs.yml | 87 ++++++++++++++++++++++++++++ solidity/.prettierignore | 1 + solidity/docgen-templates/common.hbs | 33 +++++++++++ solidity/hardhat.config.ts | 7 +++ solidity/package.json | 1 + solidity/yarn.lock | 44 +++++++++++++- 6 files changed, 171 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/contracts-docs.yml create mode 100644 solidity/docgen-templates/common.hbs diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml new file mode 100644 index 000000000..30cf15d16 --- /dev/null +++ b/.github/workflows/contracts-docs.yml @@ -0,0 +1,87 @@ +name: Solidity docs + +on: + pull_request: + push: + branches: + - releases/mainnet/solidity/** + release: + types: + - "published" + workflow_dispatch: + +jobs: + docs-detect-changes: + runs-on: ubuntu-latest + outputs: + path-filter: ${{ steps.filter.outputs.path-filter }} + steps: + - uses: actions/checkout@v3 + if: github.event_name == 'pull_request' + - uses: dorny/paths-filter@v2 + if: github.event_name == 'pull_request' + id: filter + with: + filters: | + path-filter: + - './solidity/contracts/**' + - './.github/workflows/solidity-docs.yml' + + # This job will be triggered for PRs which modify contracts. It will generate + # the archive with contracts documentation in Markdown and attatch it to the + # workflow run results. Link to the archive will be posted in a PR comment. + # The job will also be run after manual triggering and after pushes to the + # `releases/mainnet/solidity/**` branches. + contracts-docs-publish-preview: + name: Publish preview of contracts documentation + needs: docs-detect-changes + if: | + github.event_name == 'pull_request' + || github.event_name == 'push' + || github.event_name == 'workflow_dispatch' + uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main + with: + projectSubfolder: /solidity + # We need to remove unnecessary `//` comment used in the `@dev` + # section of `BitcoinTx` documentation, which was causing problem with + # rendering of the `.md` file. We do that by executing + # `sed -i ':a;N;$!ba;s_///\n//\n_///\n_g'` on the problematic file. The + # command substitutes `///` + newline + `//` + newline with just `///` + + # newline and does this in a loop. + preProcessingCommand: sed -i ':a;N;$!ba;s_///\n//\n_///\n_g' ./contracts/bridge/BitcoinTx.sol + publish: false + commentPR: true + exportAsGHArtifacts: true + + # This job will be triggered for releases which name starts with + # `refs/tags/solidity/`. It will generate contracts documentation in + # Markdown and sync it with a specific path of + # `threshold-network/threshold` repository. If changes will be detected, + # the destination repository will be updated. The commit pushing the + # changes will be verified using GPG key. + contracts-docs-publish: + name: Publish contracts documentation + needs: docs-detect-changes + if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/') + uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main + with: + projectSubfolder: /solidity + # We need to remove unnecessary `//` comment used in the `@dev` + # section of `BitcoinTx` documentation, which was causing problem with + # rendering of the `.md` file. We do that by executing + # `sed -i ':a;N;$!ba;s_///\n//\n_///\n_g'` on the problematic file. The + # command substitutes `///` + newline + `//` + newline with just `///` + + # newline and does this in a loop. + preProcessingCommand: sed -i ':a;N;$!ba;s_///\n//\n_///\n_g' ./contracts/bridge/BitcoinTx.sol + # TODO: change publish to true, uncomment other params below, change branch to `main` + publish: true + verifyCommits: true + destinationRepo: threshold-network/threshold + destinationFolder: ./docs/app-development/tbtc-v2/tbtc-v2-api + destinationBranch: main + userEmail: thesis-heimdall@users.noreply.github.com + userName: Heimdall + secrets: + githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }} + gpgPrivateKey: ${{ secrets.GPG_PRIVATE_KEY }} + gpgPassphrase: ${{ secrets.GPG_PASSPHRASE }} diff --git a/solidity/.prettierignore b/solidity/.prettierignore index 6d3a1b378..a0e5f649c 100644 --- a/solidity/.prettierignore +++ b/solidity/.prettierignore @@ -6,4 +6,5 @@ deployments/ export/ hardhat-dependency-compiler/ typechain/ +docgen-templates/ export.json diff --git a/solidity/docgen-templates/common.hbs b/solidity/docgen-templates/common.hbs new file mode 100644 index 000000000..564f17b45 --- /dev/null +++ b/solidity/docgen-templates/common.hbs @@ -0,0 +1,33 @@ +{{h}} {{name}} + +{{#if signature}} +```solidity +{{{signature}}} +``` +{{/if}} + +{{{natspec.notice}}} + +{{#if natspec.dev}} +{{{natspec.dev}}} +{{/if}} + +{{#if natspec.params}} +{{h 2}} Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +{{#each params}} +| {{name}} | {{type}} | {{{joinLines natspec}}} | +{{/each}} +{{/if}} + +{{#if natspec.returns}} +{{h 2}} Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +{{#each returns}} +| {{#if name}}{{name}}{{else}}[{{@index}}]{{/if}} | {{type}} | {{{joinLines natspec}}} | +{{/each}} +{{/if}} \ No newline at end of file diff --git a/solidity/hardhat.config.ts b/solidity/hardhat.config.ts index 18312cdb1..f10501fc0 100644 --- a/solidity/hardhat.config.ts +++ b/solidity/hardhat.config.ts @@ -11,6 +11,7 @@ import "hardhat-deploy" import "@tenderly/hardhat-tenderly" import "@typechain/hardhat" import "hardhat-dependency-compiler" +import "solidity-docgen" const ecdsaSolidityCompilerConfig = { version: "0.8.17", @@ -246,6 +247,12 @@ const config: HardhatUserConfig = { typechain: { outDir: "typechain", }, + docgen: { + outputDir: "generated-docs", + templates: "docgen-templates", + pages: "single", // `single`, `items` or `files` + exclude: ["./test"], + }, } export default config diff --git a/solidity/package.json b/solidity/package.json index c4c1c9ad2..f3ee6bd36 100644 --- a/solidity/package.json +++ b/solidity/package.json @@ -69,6 +69,7 @@ "prettier-plugin-solidity": "^1.0.0-beta.19", "solhint": "^3.3.7", "solhint-config-keep": "github:keep-network/solhint-config-keep", + "solidity-docgen": "^0.6.0-beta.34", "ts-node": "^10.4.0", "typechain": "^6.1.0", "typescript": "^4.5.4" diff --git a/solidity/yarn.lock b/solidity/yarn.lock index 221f88bce..a3acc9996 100644 --- a/solidity/yarn.lock +++ b/solidity/yarn.lock @@ -108,7 +108,7 @@ resolved "https://registry.yarnpkg.com/@celo/utils/-/utils-0.1.11.tgz#c35e3b385091fc6f0c0c355b73270f4a8559ad38" integrity sha512-i3oK1guBxH89AEBaVA1d5CHnANehL36gPIcSpPBWiYZrKTGGVvbwNmVoaDwaKFXih0N22vXQAf2Rul8w5VzC3w== dependencies: - "@umpirsky/country-list" "git+https://github.com/umpirsky/country-list#05fda51" + "@umpirsky/country-list" "git://github.com/umpirsky/country-list#05fda51" bigi "^1.1.0" bignumber.js "^9.0.0" bip32 "2.0.5" @@ -7442,6 +7442,18 @@ growl@1.10.5: resolved "https://registry.yarnpkg.com/growl/-/growl-1.10.5.tgz#f2735dc2283674fa67478b10181059355c369e5e" integrity sha512-qBr4OuELkhPenW6goKVXiv47US3clb3/IbuWF9KNKEijAy9oeHxU9IgzjvJhHkUzhaj7rOUD7+YGWqUjLp5oSA== +handlebars@^4.7.7: + version "4.7.7" + resolved "https://registry.yarnpkg.com/handlebars/-/handlebars-4.7.7.tgz#9ce33416aad02dbd6c8fafa8240d5d98004945a1" + integrity sha512-aAcXm5OAfE/8IXkcZvCepKU3VzW1/39Fb5ZuqMtgI/hT8X2YgoMvBY5dLhq/cpOvw7Lk1nK/UF71aLG/ZnVYRA== + dependencies: + minimist "^1.2.5" + neo-async "^2.6.0" + source-map "^0.6.1" + wordwrap "^1.0.0" + optionalDependencies: + uglify-js "^3.1.4" + har-schema@^2.0.0: version "2.0.0" resolved "https://registry.yarnpkg.com/har-schema/-/har-schema-2.0.0.tgz#a94c2224ebcac04782a0d9035521f24735b7ec92" @@ -9535,6 +9547,11 @@ negotiator@0.6.3: resolved "https://registry.yarnpkg.com/negotiator/-/negotiator-0.6.3.tgz#58e323a72fedc0d6f9cd4d31fe49f51479590ccd" integrity sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg== +neo-async@^2.6.0: + version "2.6.2" + resolved "https://registry.yarnpkg.com/neo-async/-/neo-async-2.6.2.tgz#b4aafb93e3aeb2d8174ca53cf163ab7d7308305f" + integrity sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw== + next-tick@^1.1.0: version "1.1.0" resolved "https://registry.yarnpkg.com/next-tick/-/next-tick-1.1.0.tgz#1836ee30ad56d67ef281b22bd199f709449b35eb" @@ -11358,11 +11375,24 @@ solidity-ast@^0.4.15: resolved "https://registry.yarnpkg.com/solidity-ast/-/solidity-ast-0.4.32.tgz#ba613ca24c7c79007798033e8a0f32a71285f09e" integrity sha512-vCx17410X+NMnpLVyg6ix4NMCHFIkvWrJb1rPBBeQYEQChX93Zgb9WB9NaIY4zpsr3Q8IvAfohw+jmuBzGf8OQ== +solidity-ast@^0.4.38: + version "0.4.45" + resolved "https://registry.yarnpkg.com/solidity-ast/-/solidity-ast-0.4.45.tgz#37c1c17bd79123106fc69d94b4a8e9237ae8c625" + integrity sha512-N6uqfaDulVZqjpjru+KvMLjV89M3hesyr/1/t8nkjohRagFSDmDxZvb9viKV98pdwpMzs61Nt2JAApgh0fkL0g== + solidity-comments-extractor@^0.0.7: version "0.0.7" resolved "https://registry.yarnpkg.com/solidity-comments-extractor/-/solidity-comments-extractor-0.0.7.tgz#99d8f1361438f84019795d928b931f4e5c39ca19" integrity sha512-wciNMLg/Irp8OKGrh3S2tfvZiZ0NEyILfcRCXCD4mp7SgK/i9gzLfhY2hY7VMCQJ3kH9UB9BzNdibIVMchzyYw== +solidity-docgen@^0.6.0-beta.34: + version "0.6.0-beta.34" + resolved "https://registry.yarnpkg.com/solidity-docgen/-/solidity-docgen-0.6.0-beta.34.tgz#f1766b13ea864ea71b8e727796d30a69ea90014a" + integrity sha512-igdGrkg8gT1jn+B2NwzjEtSf+7NTrSi/jz88zO7MZWgETmcWbXaxgAsQP4BQeC4YFeH0Pie1NsLP7+9qDgvFtA== + dependencies: + handlebars "^4.7.7" + solidity-ast "^0.4.38" + source-map-resolve@^0.5.0: version "0.5.3" resolved "https://registry.yarnpkg.com/source-map-resolve/-/source-map-resolve-0.5.3.tgz#190866bece7553e1f8f267a2ee82c606b5509a1a" @@ -11415,7 +11445,7 @@ source-map@^0.5.6, source-map@^0.5.7: resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.5.7.tgz#8a039d2d1021d22d1ea14c80d8ea468ba2ef3fcc" integrity sha1-igOdLRAh0i0eoUyA2OpGi6LvP8w= -source-map@^0.6.0: +source-map@^0.6.0, source-map@^0.6.1: version "0.6.1" resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.6.1.tgz#74722af32e9614e9c287a8d0bbde48b5e2f1a263" integrity sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g== @@ -12323,6 +12353,11 @@ typical@^5.2.0: resolved "https://registry.yarnpkg.com/typical/-/typical-5.2.0.tgz#4daaac4f2b5315460804f0acf6cb69c52bb93066" integrity sha512-dvdQgNDNJo+8B2uBQoqdb11eUCE1JQXhvjC/CZtgvZseVd5TYMXnq0+vuUemXbd/Se29cTaUuPX3YIc2xgbvIg== +uglify-js@^3.1.4: + version "3.17.4" + resolved "https://registry.yarnpkg.com/uglify-js/-/uglify-js-3.17.4.tgz#61678cf5fa3f5b7eb789bb345df29afb8257c22c" + integrity sha512-T9q82TJI9e/C1TAxYvfb16xO120tMVFZrGA3f9/P4424DNu6ypK103y0GPFVa17yotwSyZW5iYXgjYHkGrJW/g== + ultron@~1.1.0: version "1.1.1" resolved "https://registry.yarnpkg.com/ultron/-/ultron-1.1.1.tgz#9fe1536a10a664a65266a1e3ccf85fd36302bc9c" @@ -13679,6 +13714,11 @@ word-wrap@^1.2.3, word-wrap@~1.2.3: resolved "https://registry.yarnpkg.com/word-wrap/-/word-wrap-1.2.3.tgz#610636f6b1f703891bd34771ccb17fb93b47079c" integrity sha512-Hz/mrNwitNRh/HUAtM/VT/5VH+ygD6DV7mYKZAtHOrbs8U7lvPS6xf7EJKMF0uW1KJCl0H701g3ZGus+muE5vQ== +wordwrap@^1.0.0: + version "1.0.0" + resolved "https://registry.yarnpkg.com/wordwrap/-/wordwrap-1.0.0.tgz#27584810891456a4171c8d0226441ade90cbcaeb" + integrity sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q== + wordwrapjs@^4.0.0: version "4.0.1" resolved "https://registry.yarnpkg.com/wordwrapjs/-/wordwrapjs-4.0.1.tgz#d9790bccfb110a0fc7836b5ebce0937b37a8b98f" From bcc8a6166cd4fac74d68d604ab1a7d4ea3d67399 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Wed, 19 Apr 2023 12:11:58 +0200 Subject: [PATCH 02/15] Cleanup, fix wrong filename --- .github/workflows/contracts-docs.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index 30cf15d16..862a6e4d9 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -25,7 +25,7 @@ jobs: filters: | path-filter: - './solidity/contracts/**' - - './.github/workflows/solidity-docs.yml' + - './.github/workflows/contracts-docs.yml' # This job will be triggered for PRs which modify contracts. It will generate # the archive with contracts documentation in Markdown and attatch it to the @@ -73,7 +73,6 @@ jobs: # command substitutes `///` + newline + `//` + newline with just `///` + # newline and does this in a loop. preProcessingCommand: sed -i ':a;N;$!ba;s_///\n//\n_///\n_g' ./contracts/bridge/BitcoinTx.sol - # TODO: change publish to true, uncomment other params below, change branch to `main` publish: true verifyCommits: true destinationRepo: threshold-network/threshold From ea869cf112cc8c1c0928a194c3a6de4e2964a863 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Wed, 19 Apr 2023 13:21:44 +0200 Subject: [PATCH 03/15] Change user commiting docs We renamed Heimdall user to Valkyrie. --- .github/workflows/contracts-docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index 862a6e4d9..c945b58b1 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -78,8 +78,8 @@ jobs: destinationRepo: threshold-network/threshold destinationFolder: ./docs/app-development/tbtc-v2/tbtc-v2-api destinationBranch: main - userEmail: thesis-heimdall@users.noreply.github.com - userName: Heimdall + userEmail: thesis-valkyrie@users.noreply.github.com + userName: Valkyrie secrets: githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }} gpgPrivateKey: ${{ secrets.GPG_PRIVATE_KEY }} From 56debc1b57b90e5181d041ce4cd2d1af45f7efc6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Wed, 19 Apr 2023 14:32:51 +0200 Subject: [PATCH 04/15] Update name of the secrets --- .github/workflows/contracts-docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index c945b58b1..cb02a7692 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -82,5 +82,5 @@ jobs: userName: Valkyrie secrets: githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }} - gpgPrivateKey: ${{ secrets.GPG_PRIVATE_KEY }} - gpgPassphrase: ${{ secrets.GPG_PASSPHRASE }} + gpgPrivateKey: ${{ secrets.THRESHOLD_DOCS_GPG_PASSPHRASE }} + gpgPassphrase: ${{ secrets.THRESHOLD_DOCS_GPG_PRIVATE_KEY_BASE64 }} From 0b39289f11a75f22c2097e06c7e9d8985ad82f06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Wed, 19 Apr 2023 14:59:08 +0200 Subject: [PATCH 05/15] Update commiter's e-mail --- .github/workflows/contracts-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index cb02a7692..f5bb8e731 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -78,7 +78,7 @@ jobs: destinationRepo: threshold-network/threshold destinationFolder: ./docs/app-development/tbtc-v2/tbtc-v2-api destinationBranch: main - userEmail: thesis-valkyrie@users.noreply.github.com + userEmail: valkyrie@thesis.co userName: Valkyrie secrets: githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }} From 7591ca3dc38ea1b1ac022132023f0e13feffee2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Tue, 25 Apr 2023 10:30:58 +0200 Subject: [PATCH 06/15] Rename the input with project directory The name of the input in the reusable action has changed, we're updating the name in the jobs that use it. --- .github/workflows/contracts-docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index f5bb8e731..a065d11dc 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -41,7 +41,7 @@ jobs: || github.event_name == 'workflow_dispatch' uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main with: - projectSubfolder: /solidity + projectDir: /solidity # We need to remove unnecessary `//` comment used in the `@dev` # section of `BitcoinTx` documentation, which was causing problem with # rendering of the `.md` file. We do that by executing @@ -65,7 +65,7 @@ jobs: if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/') uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main with: - projectSubfolder: /solidity + projectDir: /solidity # We need to remove unnecessary `//` comment used in the `@dev` # section of `BitcoinTx` documentation, which was causing problem with # rendering of the `.md` file. We do that by executing From a1b07bc61c6797137514f5d7406d399191ca2336 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Wed, 3 May 2023 13:51:05 +0200 Subject: [PATCH 07/15] Update destination branch input's name We decided to push the docs updates not directly to branch synched with GitBook, but create a PR and set a GitBook-synched branch as a base branch for that PR. This resulted in changes in the `keep-network/ci/.github/workflows/reusable-solidity-docs.yml` workflow's inputs. --- .github/workflows/contracts-docs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index a065d11dc..ceff6bcad 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -57,8 +57,8 @@ jobs: # `refs/tags/solidity/`. It will generate contracts documentation in # Markdown and sync it with a specific path of # `threshold-network/threshold` repository. If changes will be detected, - # the destination repository will be updated. The commit pushing the - # changes will be verified using GPG key. + # a PR updating the docs will be created in the destination repository. The + # commit pushing the changes will be verified using GPG key. contracts-docs-publish: name: Publish contracts documentation needs: docs-detect-changes @@ -77,7 +77,7 @@ jobs: verifyCommits: true destinationRepo: threshold-network/threshold destinationFolder: ./docs/app-development/tbtc-v2/tbtc-v2-api - destinationBranch: main + destinationBaseBranch: main userEmail: valkyrie@thesis.co userName: Valkyrie secrets: From 81932a021dc90dbe086093805e14a85d69f942a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Tue, 23 May 2023 09:34:39 +0200 Subject: [PATCH 08/15] Temporarily trigger the workflow on feature branch Temporary change, only to test the workflows. Needs to be reverted. --- .github/workflows/contracts-docs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index ceff6bcad..2007796a9 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -62,7 +62,8 @@ jobs: contracts-docs-publish: name: Publish contracts documentation needs: docs-detect-changes - if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/') + # TODO: remove last OR + if: (github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')) || github.ref == 'refs/pull/584/merge' uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main with: projectDir: /solidity From ce72d9f5b6ea59881edd445e3f0e6ff01a4668ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Tue, 23 May 2023 09:55:22 +0200 Subject: [PATCH 09/15] Fix values of GPG secrets --- .github/workflows/contracts-docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index 2007796a9..6640de86a 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -83,5 +83,5 @@ jobs: userName: Valkyrie secrets: githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }} - gpgPrivateKey: ${{ secrets.THRESHOLD_DOCS_GPG_PASSPHRASE }} - gpgPassphrase: ${{ secrets.THRESHOLD_DOCS_GPG_PRIVATE_KEY_BASE64 }} + gpgPrivateKey: ${{ secrets.THRESHOLD_DOCS_GPG_PRIVATE_KEY_BASE64 }} + gpgPassphrase: ${{ secrets.THRESHOLD_DOCS_GPG_PASSPHRASE }} From 9f6ff6565d7cafb55d0a801db3ad44cd30334d1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Tue, 23 May 2023 13:59:56 +0200 Subject: [PATCH 10/15] Temporarily use action from `fix-docs-generation` branch The branch contains a step that cleans cache before running Docgen. We want to verify if this will help for the random problems with docs generation. --- .github/workflows/contracts-docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index 6640de86a..37adea8b6 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -39,7 +39,7 @@ jobs: github.event_name == 'pull_request' || github.event_name == 'push' || github.event_name == 'workflow_dispatch' - uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main + uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@fix-docs-generation # TODO: change to `main` with: projectDir: /solidity # We need to remove unnecessary `//` comment used in the `@dev` @@ -64,7 +64,7 @@ jobs: needs: docs-detect-changes # TODO: remove last OR if: (github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')) || github.ref == 'refs/pull/584/merge' - uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main + uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@fix-docs-generation # TODO: change to `main` with: projectDir: /solidity # We need to remove unnecessary `//` comment used in the `@dev` From d927ab44ae068c5ef71e6eebb78d8252ca639d34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Wed, 7 Jun 2023 15:22:23 +0200 Subject: [PATCH 11/15] Change Valkyrie's to noreply email Change introduced to fix the 'Your push would publish a private email address.' error. --- .github/workflows/contracts-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index 37adea8b6..574ed45f3 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -79,7 +79,7 @@ jobs: destinationRepo: threshold-network/threshold destinationFolder: ./docs/app-development/tbtc-v2/tbtc-v2-api destinationBaseBranch: main - userEmail: valkyrie@thesis.co + userEmail: 8324465+thesis-valkyrie@noreply.github.com userName: Valkyrie secrets: githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }} From b52d529c2a16cfa1e54b5ac11b63d544642faba8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Tue, 13 Jun 2023 10:49:01 +0200 Subject: [PATCH 12/15] Fix commiter's email The correct noreply address for Valkyrie contains the `users.` part. --- .github/workflows/contracts-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index 574ed45f3..142f2fc4f 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -79,7 +79,7 @@ jobs: destinationRepo: threshold-network/threshold destinationFolder: ./docs/app-development/tbtc-v2/tbtc-v2-api destinationBaseBranch: main - userEmail: 8324465+thesis-valkyrie@noreply.github.com + userEmail: 8324465+thesis-valkyrie@users.noreply.github.com userName: Valkyrie secrets: githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }} From 626045de6b2af4d3def582331e3671241e519277 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Tue, 20 Jun 2023 10:07:13 +0200 Subject: [PATCH 13/15] Use correct id in committer's e-mail --- .github/workflows/contracts-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index 142f2fc4f..4f88ab6ae 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -79,7 +79,7 @@ jobs: destinationRepo: threshold-network/threshold destinationFolder: ./docs/app-development/tbtc-v2/tbtc-v2-api destinationBaseBranch: main - userEmail: 8324465+thesis-valkyrie@users.noreply.github.com + userEmail: 38324465+thesis-valkyrie@users.noreply.github.com userName: Valkyrie secrets: githubToken: ${{ secrets.THRESHOLD_DOCS_GITHUB_TOKEN }} From 7d41bc93990e708aa45f7068a778f6cb34b1c811 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michalina=20Ciencia=C5=82a?= Date: Tue, 20 Jun 2023 12:55:54 +0200 Subject: [PATCH 14/15] Remove testing configuration The workflow was confirmed to work ok, we can remove the configuration that was used for testing purposes. --- .github/workflows/contracts-docs.yml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index 4f88ab6ae..394d7afe9 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -39,7 +39,7 @@ jobs: github.event_name == 'pull_request' || github.event_name == 'push' || github.event_name == 'workflow_dispatch' - uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@fix-docs-generation # TODO: change to `main` + uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main with: projectDir: /solidity # We need to remove unnecessary `//` comment used in the `@dev` @@ -62,9 +62,8 @@ jobs: contracts-docs-publish: name: Publish contracts documentation needs: docs-detect-changes - # TODO: remove last OR - if: (github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')) || github.ref == 'refs/pull/584/merge' - uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@fix-docs-generation # TODO: change to `main` + if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/') + uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main with: projectDir: /solidity # We need to remove unnecessary `//` comment used in the `@dev` From 6e37e663919126ff8588c9fd644346f6c5b8068b Mon Sep 17 00:00:00 2001 From: Michalina Date: Wed, 28 Jun 2023 10:08:18 +0200 Subject: [PATCH 15/15] Use the path filter when triggering `contracts-docs-publish-preview` Instead of running the `contracts-docs-publish-preview` job on update of every PR, we want to run it only when PR modifies contracts or the workflow itself. --- .github/workflows/contracts-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index 394d7afe9..162e54cc9 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -36,7 +36,7 @@ jobs: name: Publish preview of contracts documentation needs: docs-detect-changes if: | - github.event_name == 'pull_request' + needs.docs-detect-changes.outputs.path-filter == 'true' || github.event_name == 'push' || github.event_name == 'workflow_dispatch' uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main