Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Remove spec/ directory from each module #1

Closed
colin-axner opened this issue Feb 18, 2021 · 3 comments
Closed

Remove spec/ directory from each module #1

colin-axner opened this issue Feb 18, 2021 · 3 comments
Labels
docs Improvements or additions to documentation
Milestone
Q4-2022-backlog

Comments

@colin-axner
Copy link
Contributor

colin-axner commented Feb 18, 2021 •
edited
Loading

I find the spec/ layout to be a little clumsy. It feels like a lot of work to maintain and generally feels not super useful (I rarely look at it for modules I am unfamiliar with). For example, it feels redundant to define all the message types and explain their meanings (especially since we have godoc for this). This should be well documented in the msgs.go file imo. The spec directory should focus on high level overviews with concepts that won't change often, more detailed analysis should be delegated to the ICS spec.

We should focus on creating documentation for developers with spec/, but even then, I think having a good repository of ADRs will likely be more useful.

Since we are no longer in the SDK (and have everything specified in the ICS, unlike the SDK), we can determine what documentation structure is optimal for us in helping developers and lowering technical debt and outdated documentation.

Maybe we should remove the spec/ directory entirely? Use ADRs to document why we implemented the ICS a specific way and rely on godoc to explain basic concepts like what ProofConsensuState means for a certain message type

cc @fedekunze
@colin-axner colin-axner mentioned this issue Aug 31, 2021
Merged
9 tasks
@colin-axner colin-axner mentioned this issue Dec 15, 2021
Merged
9 tasks
@colin-axner
Copy link
Contributor Author

The SDK previously recommended each module have its own "spec" directory. Since IBC has very well specified documents in cosmos/ibc, the existence of a spec directory doesn't make much sense. Within ibc-go we should support two types of documentation:

  • documentation for external developers
  • documentation for internal developers

Internal developers should be expected to read code as a form of documentation, architecture documentation should also be read.

External developers should be expected to read the files hosted on the documentation website via the docs/ directory.

@colin-axner colin-axner changed the title Audit the spec/ directory and reformat code documentation Remove spec/ directory from each module Dec 15, 2021
@colin-axner colin-axner added the docs Improvements or additions to documentation label Dec 15, 2021
@colin-axner colin-axner added this to the vNext milestone Dec 15, 2021
@colin-axner
Copy link
Contributor Author

colin-axner commented Dec 22, 2021 •
edited by crodriguezvega
Loading

This should be done for:

chatton added a commit that referenced this issue Jul 6, 2022
@chatton
Script to dynamically generate list of e2e tests (E2E #1) (#1644)
527a11a
damiannolan added a commit that referenced this issue Jul 27, 2022
@damiannolan @charleenfei
@seantking @crodriguezvega @chatton @dependabot @vuong177 @AdityaSripal @faddat @colin-axner @renaynay @tmsdkeys @fedekunze
chore: merge latest main into 04-channel-upgrades branch (#1788)
4921ec9 
* docs: msg types for fee middleware (#1572)

* fix broken link

* fix: rm AllowUpdateAfter... check (#1118)

* update code & test

* update proto and adr026

* update CHANGELOG

* update cli docs

* update broken milestone link

* updated docs

* update re: comments

* nits: adding inline comments

Co-authored-by: Sean King <sean@seking.dev>

* chore: adding module name to incentivized packet events (#1580)

* docs: adding events to fee middleware docs (#1578)

* adding fee distribution docs for relayer operators

* adding validation information and basic cli examples

* removing unnecessary whitespace

* updating definitions

* adding ics29 fee middleware events docs

* cleanup

Co-authored-by: Sean King <seantking@users.noreply.github.com>

* docs: adding End Users section to ics29 docs (#1579)

* docs: adding End Users section to ics29 docs

* Update docs/middleware/ics29-fee/end-users.md

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

* Update docs/middleware/ics29-fee/end-users.md

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

* Update docs/middleware/ics29-fee/end-users.md

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

* Update docs/middleware/ics29-fee/end-users.md

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

* Update docs/middleware/ics29-fee/end-users.md

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

* Update docs/middleware/ics29-fee/end-users.md

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

* Update docs/middleware/ics29-fee/end-users.md

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

* Update docs/middleware/ics29-fee/end-users.md

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

* Update docs/middleware/ics29-fee/end-users.md

Co-authored-by: Damian Nolan <damiannolan@gmail.com>

* chore: add link

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>
Co-authored-by: Damian Nolan <damiannolan@gmail.com>

* feat: emitting an event when handling a client upgrade proposal (#1570)

* feat: emitting an event when handling a client upgrade proposal

* refactor: only emit event if err is nil

* refactor: idiotmatic go:

* docs: nits (#1595)

* docs: document that version string can be empty as argument of RegisterInterchainAccount (#1582)

Co-authored-by: Carlos Rodriguez <crodveg@gmail.com>

* docs: add upgrade client proposal event (#1596)

* Consolidate usage of NewErrorAcknowledgement (#1565)

* docs: adding line about module accounts / invariants (#1597)

* docs: adding line about module accounts / invariants

* Update docs/middleware/ics29-fee/fee-distribution.md

Co-authored-by: Damian Nolan <damiannolan@gmail.com>

* Update docs/middleware/ics29-fee/fee-distribution.md

Co-authored-by: Damian Nolan <damiannolan@gmail.com>

Co-authored-by: Damian Nolan <damiannolan@gmail.com>

* follow up nits to #1565 (#1598)

* delete test files and add error to transfer types

* review comments

* build(deps): bump github.com/stretchr/testify from 1.7.5 to 1.8.0 (#1616)

Bumps [github.com/stretchr/testify](https://github.com/stretchr/testify) from 1.7.5 to 1.8.0.
- [Release notes](https://github.com/stretchr/testify/releases)
- [Commits](stretchr/testify@v1.7.5...v1.8.0)

---
updated-dependencies:
- dependency-name: github.com/stretchr/testify
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore: bump go package version to v4 (#1564)

* chore: bump go package version to v4

* update go.mod

* fix alignment

* fix build

* review comments

* build fixes

* deps: bumping go version 1.18 (#1627)

* bumping go version 1.18

* updating broken workflow setup

* add backport to v4.0.x and remove backports to v1 (EoL) (#1629)

* delete unused 04-channel version functions (#1636)

* delete unused code and associated tests

* Update CHANGELOG.md

* build(deps): bump github.com/cosmos/cosmos-sdk from 0.45.5 to 0.45.6 (#1615)

* build(deps): bump github.com/cosmos/cosmos-sdk from 0.45.5 to 0.45.6

Bumps [github.com/cosmos/cosmos-sdk](https://github.com/cosmos/cosmos-sdk) from 0.45.5 to 0.45.6.
- [Release notes](https://github.com/cosmos/cosmos-sdk/releases)
- [Changelog](https://github.com/cosmos/cosmos-sdk/blob/main/CHANGELOG.md)
- [Commits](cosmos/cosmos-sdk@v0.45.5...v0.45.6)

---
updated-dependencies:
- dependency-name: github.com/cosmos/cosmos-sdk
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

* Update CHANGELOG.md

* copying part of codeql workflow to try to make it pass

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Carlos Rodriguez <carlos@interchain.io>
Co-authored-by: Carlos Rodriguez <crodveg@gmail.com>

* update mergify.yml with new release branches (#1654)

* Script to dynamically generate list of e2e tests (E2E #1) (#1644)

* Add GitHub actions for e2e tests (E2E #2) (#1646)

* Remove crossings hello (#1317)

* remove crossing hellos from ChanOpenTry

* remove crossing hellos testcase

* revert single connectionHops check

* add comment in MsgChannelOpenTry tx proto about deprecate field

* Update proto/ibc/core/channel/v1/tx.proto

Co-authored-by: Aditya <adityasripal@gmail.com>

* minor fixes && UPDATE CHANGELOG.md

* Update proto/ibc/core/channel/v1/tx.proto

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

* Update proto/ibc/core/channel/v1/tx.proto

Co-authored-by: Damian Nolan <damiannolan@gmail.com>

* apply remaining changes for crossing hello removal

Deprecate previous channel id with proto tag
Remove unnecessary test cases from 04-channel
Remove crossing hello check in transfer application and the associated test case

* remove previous channel check in WriteChannelOpenTry

* regenerate proto files

* update documentation

* add migration documentation

* remove unnecessary doc

* remove crossing hello notion from ChanOpenAck

* apply review suggestions

Co-authored-by: Aditya <adityasripal@gmail.com>
Co-authored-by: Carlos Rodriguez <carlos@interchain.io>
Co-authored-by: Damian Nolan <damiannolan@gmail.com>
Co-authored-by: Jacob Gadikian <jacobgadikian@gmail.com>
Co-authored-by: Colin Axnér <25233464+colin-axner@users.noreply.github.com>

* docs: update roadmap (#1678)

* update roadmap

* update roadmap

* Update roadmap.md

Co-authored-by: Carlos Rodriguez <crodveg@gmail.com>

* refactor: remove crossing hellos from 03-connection (#1672)

* remove crossing hello check from ConnOpenTry and ConnOpenAck

* remove unnecessary test cases and fix build

* fix tests and add migration docs

* fix connection version check in conn open ack

* add changelog entry

* Update modules/core/03-connection/keeper/handshake.go

Co-authored-by: Aditya <adityasripal@gmail.com>

* remove unnecessary testing function

* improve migration documentation as per review suggestion

Co-authored-by: Aditya <adityasripal@gmail.com>

* (core/23-commitment/types) doc: fix typo (#1694)

* remove spurious `TestABCICodeDeterminism` tests (#1695)

## Description

Thanks @colin-axner for noticing this.

closes: #XXXX

---

Before we can merge this PR, please make sure that all the following items have been
checked off. If any of the checklist items are not applicable, please leave them but
write a little note why.

- [x] Targeted PR against correct branch (see [CONTRIBUTING.md](https://github.com/cosmos/ibc-go/blob/master/CONTRIBUTING.md#pr-targeting))
- [ ] Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
- [ ] Code follows the [module structure standards](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules/structure.md).
- [ ] Wrote unit and integration [tests](https://github.com/cosmos/ibc-go/blob/master/CONTRIBUTING.md#testing)
- [ ] Updated relevant documentation (`docs/`) or specification (`x/<module>/spec/`)
- [ ] Added relevant `godoc` [comments](https://blog.golang.org/godoc-documenting-go-code).
- [ ] Added a relevant changelog entry to the `Unreleased` section in `CHANGELOG.md`
- [x] Re-reviewed `Files changed` in the Github PR explorer
- [ ] Review `Codecov Report` in the comment section below once CI passes

* update bug report issue template (#1693)

* fix codeowners for 02-client (#1696)

## Description

Thanks again @colin-axner for signaling this!

closes: #XXXX

---

Before we can merge this PR, please make sure that all the following items have been
checked off. If any of the checklist items are not applicable, please leave them but
write a little note why.

- [x] Targeted PR against correct branch (see [CONTRIBUTING.md](https://github.com/cosmos/ibc-go/blob/master/CONTRIBUTING.md#pr-targeting))
- [ ] Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
- [ ] Code follows the [module structure standards](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules/structure.md).
- [ ] Wrote unit and integration [tests](https://github.com/cosmos/ibc-go/blob/master/CONTRIBUTING.md#testing)
- [ ] Updated relevant documentation (`docs/`) or specification (`x/<module>/spec/`)
- [ ] Added relevant `godoc` [comments](https://blog.golang.org/godoc-documenting-go-code).
- [ ] Added a relevant changelog entry to the `Unreleased` section in `CHANGELOG.md`
- [x] Re-reviewed `Files changed` in the Github PR explorer
- [ ] Review `Codecov Report` in the comment section below once CI passes

* build(deps): bump google.golang.org/grpc from 1.47.0 to 1.48.0 (#1699)

Bumps [google.golang.org/grpc](https://github.com/grpc/grpc-go) from 1.47.0 to 1.48.0.
- [Release notes](https://github.com/grpc/grpc-go/releases)
- [Commits](grpc/grpc-go@v1.47.0...v1.48.0)

---
updated-dependencies:
- dependency-name: google.golang.org/grpc
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* docs: update middleware documentation (#1639)

* docs: update middleware documentation

* remove old text and add func keyword

* alignment

* fix alignment

* Update develop.md

* review comments

* remove empty line

* docs: add links in middleware docs to fee middleware implementation (#1641)

* docs: add links in middleware docs to fee middleware implementation

* add extra line for better readability

* fix typos

* Adding github action to run goimports (#1673)

* Add E2ETestSuite Type (E2E #3) (#1650)

* Separate go mod for e2e (E2E #4) (#1701)

* put back module name in event (#1681)

* fix typo

* Extracting e2e tests into two separate workflows (#1719)

* add categories

* Add fee middleware test suite functions (E2E #5) (#1710)

* Build local image to run tests with make e2e-test (#1722)

* Remove leftover crossing hello tests in connection handshake (#1724)

* remove leftover crossing hello tests in connection handshake

* fix bug in tests

* chore: adding environment variable to specify go relayer image (#1727)

* Thomas/1584 update docs apps (#1675)

* restructure content according to outline, fix image and syntax highlighting, fix titles and prepare for content updates

* rewrite bind port section

* restructure applications doc into folder structure

* add keeper section, make some minor corrections in bind ports, custom packet and implmenent IBC module sections

* update ibcmodule interface to encorporate the simpliefied handshake callbacks and version negotiation

* fix broken links

* fix remaining broken link

* fix some nits, correct for removal of crossing hellos and add some more explanation on portIDs

* update middleware docs to resolve merge confilicts

* update fee mw docs, add formating, fix typos, increase readability (#1665)

* update fee mw docs, add formating, fix typos, increase readability

* fix broken link

* Apply suggestions from code review

(De)capitalize headings and references to headings for consistency

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

* resolving merge conflict

* split the CLI commands and small typo correction

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

* chore: remove @fedekunze from CODEOWNERS (#1733)

* Test for AsyncSingleSender (E2E #6) (#1682)

* fix: running e2e-fork for dependabot PRs (#1745)

* Adding manual triggering of e2e via workflow dispatch (#1749)

* chore: denom traces migration handler (#1680)

* update code & test

* register migrator service

* add changelog entry for #1680

* add issue templates for epics and releases (#1702)

* add issue templates for epics and releases

* remove text

Co-authored-by: Carlos Rodriguez <crodveg@gmail.com>

* fix typo

* fix typo

* feat: allow governance to update the TrustingPeriod of the 07-tendermint light client (#1713)

* initial commit

* format imports

* update docs

* update CHANGELOG

* update upgrade dev docs

* update re: pr comments

* E2E Test: TestMsgPayPacketFeeSingleSender (#1756)

* move entry to right place

* build(deps): bump docker/build-push-action from 3.0.0 to 3.1.0 (#1743)

Bumps [docker/build-push-action](https://github.com/docker/build-push-action) from 3.0.0 to 3.1.0.
- [Release notes](https://github.com/docker/build-push-action/releases)
- [Commits](docker/build-push-action@e551b19...1cb9d22)

---
updated-dependencies:
- dependency-name: docker/build-push-action
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

* chore: Update makefile (#1770)

* remove unused tools, remove incorrect import formatting

* uncomment command in makefile

* add version matrix (#1767)

* add pseudocode to handle empty version string in OnChanOpenInit

* fix broken link (#1776)

* add item to update the version matrix after a release (#1775)

* E2E Test: TestMsgPayPacketFeeSingleSenderTimesOut (#1751)

* Move scripts from .github directory into cmd (#1787)

Co-authored-by: Charly <charly@interchain.berlin>
Co-authored-by: Sean King <sean@seking.dev>
Co-authored-by: Sean King <seantking@users.noreply.github.com>
Co-authored-by: Carlos Rodriguez <carlos@interchain.io>
Co-authored-by: Carlos Rodriguez <crodveg@gmail.com>
Co-authored-by: Cian Hatton <cian@interchain.io>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: vuong <56973102+vuong177@users.noreply.github.com>
Co-authored-by: Aditya <adityasripal@gmail.com>
Co-authored-by: Jacob Gadikian <jacobgadikian@gmail.com>
Co-authored-by: Colin Axnér <25233464+colin-axner@users.noreply.github.com>
Co-authored-by: rene <41963722+renaynay@users.noreply.github.com>
Co-authored-by: tmsdkeys <98807841+tmsdkeys@users.noreply.github.com>
Co-authored-by: Federico Kunze Küllmer <31522760+fedekunze@users.noreply.github.com>
alizahidraja pushed a commit to alizahidraja/ibc-go that referenced this issue Sep 29, 2022
@Daniyal98
Merge pull request cosmos#1 from alizahidraja/patch-1
5955ef8 
fixed import error
sainoe added a commit to sainoe/ibc-go that referenced this issue Dec 2, 2022
@sainoe
Merge pull request cosmos#1 from informalsystems/danwt/support-differ…
1f45da8 
…ent-app.go

Pass through an AppIniter func to be able to launch chains with different apps
ulbqb referenced this issue in ulbqb/ibc-go Feb 10, 2023
@dudong2
feat: apply the ibc module of lbm-sdk (#1)
c366ca9 
* feat: based on lbm-sdk

* feat: base on lbm-sdk(non .go files)

* chore: fit to lbm-sdk

* chore: remove lbm-sdk replace from go.mod

* chore: commit go.sum

* test: change go get to go install

* test: fix lint

* test: fix lint

* test: fix build test

* revert: inappropriate change

* feat: update proto

* feat: update swagger

* add tendermint proto

* chore: add versions and change module path
@colin-axner
Copy link
Contributor Author

closing as this is now the same issue as #135. Wahoo finally closed #1! 🎉

github-merge-queue bot pushed a commit that referenced this issue Jun 19, 2024
@chatton
Restructure E2Es to setup chain in SetupSuite and create channel in S…
10aa0ef 
…etupTest #1 (#6629)

* wip: refactoring tests to create chains in SetupSuite

* chore: refactoring memo test to use new setup fns

* chore: replace calls to setup chains and relayer with calls to get relayer and get channel

* chore: fix wiring in ThreeChainSetup

* chore: remove unused fn

* chore: add modification function based on chain inputs

* chore: update grandpa test with new structure

* chore: remove single chain methods

* chore: move upgrade tests into different files

* chore: fixing client tests

* chore: use paths associated with the test

* chore: add getter to fetch paths

* chore: fix client tests

* chore: fix misbehaviour test

* chore: fix misbehaviour test

* chore: mereg main

* chore: pr feedback
bznein pushed a commit that referenced this issue Jun 26, 2024
@chatton @bznein
Restructure E2Es to setup chain in SetupSuite and create channel in S…
d758ef3 
…etupTest #1 (#6629)

* wip: refactoring tests to create chains in SetupSuite

* chore: refactoring memo test to use new setup fns

* chore: replace calls to setup chains and relayer with calls to get relayer and get channel

* chore: fix wiring in ThreeChainSetup

* chore: remove unused fn

* chore: add modification function based on chain inputs

* chore: update grandpa test with new structure

* chore: remove single chain methods

* chore: move upgrade tests into different files

* chore: fixing client tests

* chore: use paths associated with the test

* chore: add getter to fetch paths

* chore: fix client tests

* chore: fix misbehaviour test

* chore: fix misbehaviour test

* chore: mereg main

* chore: pr feedback
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Improvements or additions to documentation
Projects
ibc-go
Status: Done 🥳
Milestone
Q4-2022-backlog
Development

No branches or pull requests
2 participants
@crodriguezvega @colin-axner