diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index fae32a106a..785936d886 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -16,7 +16,7 @@ v Please also ensure that this is not a duplicate issue :) ## Version - + ## Steps to Reproduce diff --git a/.github/ISSUE_TEMPLATE/release-template.md b/.github/ISSUE_TEMPLATE/release-template.md index e1f3734d07..5fe55f8f4d 100644 --- a/.github/ISSUE_TEMPLATE/release-template.md +++ b/.github/ISSUE_TEMPLATE/release-template.md @@ -19,4 +19,3 @@ v without deliberation - If doing a release candidate (`rc`) version, then skip the `unclog release` step. - [ ] Bump all crate versions to the new version. - [ ] Reassign unfinished issues of previous milestone to the next milestone. -- [ ] Update Cargo.lock file (if re-publishing `ibc-relayer-cli`) diff --git a/.github/ISSUE_TEMPLATE/rust-update.md b/.github/ISSUE_TEMPLATE/rust-update.md index 2763d111ec..3eaae89a7e 100644 --- a/.github/ISSUE_TEMPLATE/rust-update.md +++ b/.github/ISSUE_TEMPLATE/rust-update.md @@ -20,9 +20,6 @@ Rust version: - [ ] Update the `rust-version` fields in all `Cargo.toml` files. - [ ] Update the `msrv` field in `clippy.toml` and fix all lints reported by `cargo clippy --all-features`. -- [ ] Update the MSRV shields in README files: - - `README.md` - - `relayer-rest/README.md` -- [ ] Update the MSRV in the guide: `guide/src/pre_requisites.md` +- [ ] Update the MSRV shields in `README.md` file. - [ ] Add a `.changelog` entry to the `breaking-changes` section, announcing the new MSRV. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 416c404594..3f13d68f32 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -17,7 +17,7 @@ ______ ### PR author checklist: - [ ] Added changelog entry, using [`unclog`](https://github.com/informalsystems/unclog). -- [ ] Added tests: integration (for Hermes) or unit/mock tests (for modules). +- [ ] Added tests. - [ ] Linked to GitHub issue. - [ ] Updated code comments and documentation (e.g., `docs/`). - [ ] Tagged *one* reviewer who will be the one responsible for shepherding this PR. diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 483f1b00b1..fb75b48610 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -3,41 +3,8 @@ version: 2 updates: - # Enable version updates for npm - package-ecosystem: "cargo" - # Look for Cargo `.toml` and `.lock` files in the `root` directory - directory: "/" - # Check the cargo registry for updates every day (weekdays) - schedule: - interval: "weekly" - - - package-ecosystem: "cargo" - directory: "modules" - schedule: - interval: "weekly" - - - package-ecosystem: "cargo" - directory: "proto" - schedule: - interval: "weekly" - -## Disable dependabot for `proto-compiler`. -## Rationale: we maintain the dependencies for proto-compiler -## manually, so that we update the proto-compiler binary -## (and the Cargo.lock file) only when we regenerate -## Rust types from the .proto files. -# - package-ecosystem: "cargo" -# directory: "proto-compiler" -# schedule: -# interval: "weekly" - - - package-ecosystem: "cargo" - directory: "relayer" - schedule: - interval: "weekly" - - - package-ecosystem: "cargo" - directory: "relayer-cli" + directory: "crates/ibc" schedule: interval: "weekly" diff --git a/.github/workflows/no-std.yaml b/.github/workflows/no-std.yaml index d9020d1de1..f2e0c34079 100644 --- a/.github/workflows/no-std.yaml +++ b/.github/workflows/no-std.yaml @@ -6,17 +6,15 @@ on: - Cargo.toml - Cargo.lock - ci/** - - proto/** - - modules/** + - crates/** push: - branches: master + branches: main paths: - .github/workflows/no-std.yml - Cargo.toml - Cargo.lock - ci/** - - proto/** - - modules/** + - crates/** jobs: check-no-std-panic-conflict: diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index d6506276d2..d7c0cb6daf 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -4,31 +4,15 @@ on: paths: - .github/workflows/rust.yml - Cargo.toml - - Cargo.lock - ci/** - - e2e/** - - proto/** - - modules/** - - relayer/** - - relayer-cli/** - - relayer-rest/** - - telemetry/** - - tools/** + - crates/** push: - branches: master + branches: main paths: - .github/workflows/rust.yml - Cargo.toml - - Cargo.lock - ci/** - - e2e/** - - proto/** - - modules/** - - relayer/** - - relayer-cli/** - - relayer-rest/** - - telemetry/** - - tools/** + - crates/** env: CARGO_INCREMENTAL: 0 @@ -45,7 +29,7 @@ jobs: - uses: rokroskar/workflow-run-cleanup-action@master env: GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" - if: "!startsWith(github.ref, 'refs/tags/') && github.ref != 'refs/heads/master'" + if: "!startsWith(github.ref, 'refs/tags/') && github.ref != 'refs/heads/main'" fmt: runs-on: ubuntu-latest @@ -88,7 +72,7 @@ jobs: - uses: actions-rs/clippy-check@v1 with: token: ${{ secrets.GITHUB_TOKEN }} - args: --no-default-features --all-targets + args: --no-default-features test-stable: runs-on: ubuntu-latest @@ -107,7 +91,7 @@ jobs: - uses: actions-rs/cargo@v1 with: command: test - args: --all-features --no-fail-fast --workspace --exclude ibc-integration-test -- --nocapture + args: --all-features --no-fail-fast --workspace -- --nocapture # test-coverage: # runs-on: ubuntu-latest diff --git a/.gitignore b/.gitignore index 2e9b0e8816..9e29b6487f 100644 --- a/.gitignore +++ b/.gitignore @@ -27,3 +27,5 @@ mc.log # Ignore OSX .DS_Store file .DS_Store + +Cargo.lock diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..263dc36e5e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,258 @@ +# Contributing + +Thank you for your interest in contributing! The goal +of ibc-rs is to provide a high quality, formally verified implementation of +the IBC protocol. + +All work on the code base should be motivated by a Github +issue. Before opening a new issue, first do a search of open and closed issues +to make sure that yours will not be a duplicate. +If you would like to work on an issue which already exists, please indicate so +by leaving a comment. If what you'd like to work on hasn't already been covered +by an issue, then open a new one to get the process going. + +The rest of this document outlines the best practices for contributing to this +repository: + +- [Decision Making](#decision-making) - process for agreeing to changes +- [Forking](#forking) - fork the repo to make pull requests +- [Changelog](#changelog) - changes must be recorded in the changelog +- [Pull Requests](#pull-requests) - what makes a good pull request +- [Releases](#releases) - how to release new version of the crates + +## Decision Making + +When contributing to the project, the following process leads to the best chance of +landing the changes in `main`. + +All new contributions should start with a Github issue which captures the +problem you're trying to solve. Starting off with an issue allows for early +feedback. Once the issue is created, maintainers may request that more detailed +documentation be written in the form of a Request for Comment (RFC) or an +Architectural Decision Record +([ADR](https://github.com/cosmos/ibc-rs/blob/main/docs/architecture/README.md)). + +Discussion at the RFC stage will build collective understanding of the dimensions +of the problem and help structure conversations around trade-offs. + +When the problem is well understood but the solution leads to large +structural changes to the code base, these changes should be proposed in +the form of an [Architectural Decision Record +(ADR)](./docs/architecture/). The ADR will help build consensus on an +overall strategy to ensure that the code base maintains coherence +in the larger context. If you are not comfortable with writing an ADR, +you can open a regular issue and the maintainers will help you +turn it into an ADR. + +When the problem and the proposed solution are well understood, +changes should start with a [draft +pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) +against `main`. The draft status signals that work is underway. When the work +is ready for feedback, hitting "Ready for Review" will signal to the +maintainers to take a look. + +Implementation trajectories should aim to proceed where possible as a series +of smaller incremental changes, in the form of small PRs that can be merged +quickly. This helps manage the load for reviewers and reduces the likelihood +that PRs will sit open for long periods of time. + +![Contributing flow](https://github.com/tendermint/tendermint/blob/v0.33.6/docs/imgs/contributing.png?raw=true) + +Each stage of the process is aimed at creating feedback cycles which align +contributors and maintainers in order to ensure that: +- Contributors don’t waste their time implementing/proposing features which won’t land in `main` +- Maintainers have the necessary context in order to support and review contributions + +## Forking + +If you do not have write access to the repository, your contribution should be +made through a fork on Github. Fork the repository, contribute to your fork +(either in the `main` branch of the fork or in a separate branch), and then +make a pull request back upstream. + +When forking, add your fork's URL as a new git remote in your local copy of the +repo. For instance, to create a fork and work on a branch of it: +- Create the fork on GitHub, using the fork button. +- `cd` to the original clone of the repo on your machine +- `git remote rename origin upstream` +- `git remote add origin git@github.com: + +Now `origin` refers to your fork and `upstream` refers to the original version. +Now `git push -u origin main` to update the fork, and make pull requests +against the original repo. + +To pull in updates from the origin repo, run `git fetch upstream` followed by +`git rebase upstream/main` (or whatever branch you're working in). + +## Changelog + +Every non-trivial PR must update the [CHANGELOG](CHANGELOG.md). This is +accomplished indirectly by adding entries to the `.changelog` folder in +[`unclog`](https://github.com/informalsystems/unclog) format using the `unclog` CLI tool. +`CHANGELOG.md` will be built by whomever is responsible for performing a release just +prior to release - this is to avoid changelog conflicts prior to releases. + +### Install `unclog` + +```bash +cargo install unclog +``` + +### Examples + +Add a `.changelog` entry to signal that a bug was fixed, without mentioning any +component. + +```bash +$ unclog add -i update-unclog-instructions -s bug -n 1634 -m "Update CONTRIBUTING.md for latest version of unclog" --editor vim +``` + +Add a .changelog entry for the `ibc` crate. + +```bash +$ unclog add -c ibc -s features --id a-new-feature --issue-no 1235 -m "msg about this new-feature" --editor vim +``` + +### Preview unreleased changes + +```bash +unclog build -u +``` + +The Changelog is *not* a record of what Pull Requests were merged; +the commit history already shows that. The Changelog is a notice to users +about how their expectations of the software should be modified. +It is part of the UX of a release and is a *critical* user facing integration point. +The Changelog must be clean, inviting, and readable, with concise, meaningful entries. +Entries must be semantically meaningful to users. If a change takes multiple +Pull Requests to complete, it should likely have only a single entry in the +Changelog describing the net effect to the user. Instead of linking PRs directly, we +instead prefer to log issues, which tend to be higher-level, hence more relevant for users. + +When writing Changelog entries, ensure they are targeting users of the software, +not fellow developers. Developers have much more context and care about more +things than users do. Changelogs are for users. + +Changelog structure is modeled after +[Tendermint Core](https://github.com/tendermint/tendermint/blob/master/CHANGELOG.md) +and [Hashicorp Consul](http://github.com/hashicorp/consul/tree/master/CHANGELOG.md). +See those changelogs for examples. + +We currently split changes for a given release between these four sections: Breaking +Changes, Features, Improvements, Bug Fixes. + +Entries in the changelog should initially be logged in the __Unreleased__ section, which +represents a "staging area" for accumulating all the changes throughout a +release (see [Pull Requests](#pull-requests) below). With each release, +the entries then move from this section into their permanent place under a +specific release number in Changelog. + +Changelog entries should be formatted as follows: + +``` +- [pkg] Some description about the change ([#xxx](https://github.com/cosmos/ibc-rs/issues/xxx)) (optional @contributor) +``` + +Here, `pkg` is the part of the code that changed (typically a +top-level crate, but could be /), `xxx` is the issue number, and `contributor` +is the author/s of the change. + +It's also acceptable for `xxx` to refer to the relevant pull request, but issue +numbers are preferred. +Note this means issues (or pull-requests) should be opened first so the changelog can then +be updated with the corresponding number. + +Changelog entries should be ordered alphabetically according to the +`pkg`, and numerically according to their issue/PR number. + +Changes with multiple classifications should be doubly included (eg. a bug fix +that is also a breaking change should be recorded under both). + +Breaking changes are further subdivided according to the APIs/users they impact. +Any change that effects multiple APIs/users should be recorded multiply - for +instance, a change to some core protocol data structure might need to be +reflected both as breaking the core protocol but also breaking any APIs where core data structures are +exposed. + +## Pull Requests + +If you have write access to the ibc-rs repo, you can directly branch off of `main`. +This makes it easier for project maintainers to directly make changes to your +branch should the need arise. + +Branch names should be prefixed with the author's name followed by a short description +of the feature, eg. `name/feature-x`. + +Pull requests are made against `main` and are squash-merged into main. + +PRs must: +- make reference to an issue outlining the context +- update any relevant documentation and include tests +- add a corresponding entry in the `.changelog` directory using `unclog`, + see the section above for more details. + +Pull requests should aim to be small and self-contained to facilitate quick +review and merging. Larger change sets should be broken up across multiple PRs. +Commits should be concise but informative, and moderately clean. Commits will be squashed into a +single commit for the PR with all the commit messages. + +In order to help facilitate the PR review process, tag *one* person as the +reviewer of the PR. If you are unsure of who to tag, your point of contact on +the ibc-rs team is always a natural candidate; they'll make sure that the PR gets +reviewed by whomever is most appropriate to review it. It also helps to notify +the person whom you tagged as reviewer through direct means, such as through +Slack or Discord, as it is easy for GitHub notifications to get lost or buried. + +## Responsibilities of a PR Reviewer + +If you're tagged as the reviewer of a PR, you are responsible for shepherding it +through to completion. This includes fixing issues with the PR and taking the +lead on decisions that need to be resolved in order to get the PR merged. + +If you're tagged as a reviewer on a PR that affects a part of the code base that +you are unfamiliar with, you can hand it off to someone (with their +consent) who is more appropriate to shepherd the PR through to completion. + +## Releases + +Our release process is as follows: + +1. Update the [changelog](#changelog) to reflect and summarize all changes in + the release. This involves: + 1. Running `unclog build -u` and copy pasting the output at the top + of the `CHANGELOG.md` file, making sure to update the header with + the new version. + 1. Running `unclog release vX.Y.Z` to create a summary of all of the changes + in this release. + 3. Committing the updated `CHANGELOG.md` file and `.changelog` directory to the repo. +2. Push this to a branch `release/vX.Y.Z` according to the version number of + the anticipated release (e.g. `release/v0.18.0`) and open a **draft PR**. +3. Bump all relevant versions in the codebase to the new version and push these + changes to the release PR. This includes: + 1. All `Cargo.toml` files (making sure dependencies' versions are updated + too). + 2. All crates' `lib.rs` files documentation references' `html_root_url` + parameters must point to the new version. + +4. Run `cargo doc --all-features --open` locally to double-check that all the + documentation compiles and seems up-to-date and coherent. Fix any potential + issues here and push them to the release PR. +5. Mark the PR as **Ready for Review** and incorporate feedback on the release. +6. Once approved, merge the PR. +7. Pull `main` and run the [`release.sh`](./scripts/release.sh) script. + If any problem arises, submit a new PR, get it merged to `main` and try again. + The reason for not releasing straight from the release branch, and therefore losing the + ability to fix publishing problems as they arise, is that we would like the embedded + metadata of the published crates, namely the Git commit at which the release was done, + to match the Git commit on the `main` branch which will be tagged. + [See this article][crates.io-security] for a more in-depth explanation. + **Note:** This step requires the appropriate privileges to push crates to [crates.io]. +8. Once all crates have been successfully released, create a signed tag and push it to + GitHub: `git tag -s -a vX.Y.Z`. In the tag message, write the version and the link + to the corresponding section of the changelog. +9. Once the tag is pushed, wait for the CI bot to create a GitHub release, and update + the release description to `[📖 CHANGELOG](https://github.com/cosmos/ibc-rs/blob/main/CHANGELOG.md#vXYZ)`. +10. All done! 🎉 + +[crates.io]: https://crates.io +[crates.io-security]: https://codeandbitters.com/published-crate-analysis/ diff --git a/Cargo.toml b/Cargo.toml index de0e422420..1940d2fb23 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,26 +3,12 @@ resolver = "2" members = [ - "crates/ibc-chain-registry", - "crates/modules", - "crates/relayer", - "crates/relayer-cli", - "crates/relayer-rest", - "crates/telemetry", - "crates/proto", - "tools/integration-test", - "tools/test-framework", + "crates/ibc", ] exclude = [ "ci/no-std-check", - "tools/proto-compiler" ] -# [patch.crates-io] -# tendermint = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" } -# tendermint-rpc = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" } -# tendermint-proto = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" } -# tendermint-light-client = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" } -# tendermint-light-client-verifier = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" } -# tendermint-testgen = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" } +[patch.crates-io] +ibc-proto = { git = "https://github.com/hu55a1n1/ibc-proto" } diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000000..58b61ab0f6 --- /dev/null +++ b/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2020 Informal Systems + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md new file mode 100644 index 0000000000..439e5d9557 --- /dev/null +++ b/README.md @@ -0,0 +1,66 @@ +# ibc-rs + +[![Cosmos ecosystem][cosmos-shield]][cosmos-link] + +[![Docs][docs-image]][docs-link] +[![Build Status][build-image]][build-link] +[![Apache 2.0 Licensed][license-image]][license-link] +![Rust Stable][rustc-image] +![Rust 1.60+][rustc-version] + +Rust implementation of the Inter-Blockchain Communication (IBC) protocol. This project hosts +the `ibc` rust crate which defines the main data structures and on-chain logic for the IBC protocol. + +See the [ibc](crates/ibc) crate's README.md for more detailed information on the `ibc` crate. + +## Contributing + +IBC is specified in English in the [cosmos/ibc repo][ibc]. Any +protocol changes or clarifications should be contributed there. + +This repo contains the Rust implementation for the IBC modules. If you're interested in +contributing, please comment on an issue or open a new one! + +See also [CONTRIBUTING.md](./CONTRIBUTING.md). + +## Versioning + +We follow [Semantic Versioning][semver], though APIs are still +under active development. + +## Resources + +- [IBC Website][ibc-homepage] +- [IBC Specification][ibc] +- [IBC Go implementation][ibc-go] + +## License + +Copyright © 2022 Informal Systems Inc. and ibc-rs authors. + +Licensed under the Apache License, Version 2.0 (the "License"); you may not use the files in this repository except in compliance with the License. You may +obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR +CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. + +[//]: # (badges) +[docs-image]: https://docs.rs/ibc/badge.svg +[docs-link]: https://docs.rs/ibc/ +[build-image]: https://github.com/cosmos/ibc-rs/workflows/Rust/badge.svg +[build-link]: https://github.com/cosmos/ibc-rs/actions?query=workflow%3ARust +[license-image]: https://img.shields.io/badge/license-Apache2.0-blue.svg +[license-link]: https://github.com/cosmos/ibc-rs/blob/main/LICENSE +[rustc-image]: https://img.shields.io/badge/rustc-stable-blue.svg +[rustc-version]: https://img.shields.io/badge/rustc-1.60+-blue.svg + +[//]: # (general links) +[ibc-rs]: https://github.com/cosmos/ibc-rs +[ibc]: https://github.com/cosmos/ibc +[ibc-go]: https://github.com/cosmos/ibc-go +[ibc-homepage]: https://cosmos.network/ibc +[cosmos-link]: https://cosmos.network +[semver]: https://semver.org/ +[cosmos-shield]: https://img.shields.io/static/v1?label=&labelColor=1B1E36&color=1B1E36&message=cosmos%20ecosystem&style=for-the-badge&logo=data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDI0LjMuMCwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4IgoJIHZpZXdCb3g9IjAgMCAyNTAwIDI1MDAiIHN0eWxlPSJlbmFibGUtYmFja2dyb3VuZDpuZXcgMCAwIDI1MDAgMjUwMDsiIHhtbDpzcGFjZT0icHJlc2VydmUiPgo8c3R5bGUgdHlwZT0idGV4dC9jc3MiPgoJLnN0MHtmaWxsOiM2RjczOTA7fQoJLnN0MXtmaWxsOiNCN0I5Qzg7fQo8L3N0eWxlPgo8cGF0aCBjbGFzcz0ic3QwIiBkPSJNMTI1Mi42LDE1OS41Yy0xMzQuOSwwLTI0NC4zLDQ4OS40LTI0NC4zLDEwOTMuMXMxMDkuNCwxMDkzLjEsMjQ0LjMsMTA5My4xczI0NC4zLTQ4OS40LDI0NC4zLTEwOTMuMQoJUzEzODcuNSwxNTkuNSwxMjUyLjYsMTU5LjV6IE0xMjY5LjQsMjI4NGMtMTUuNCwyMC42LTMwLjksNS4xLTMwLjksNS4xYy02Mi4xLTcyLTkzLjItMjA1LjgtOTMuMi0yMDUuOAoJYy0xMDguNy0zNDkuOC04Mi44LTExMDAuOC04Mi44LTExMDAuOGM1MS4xLTU5Ni4yLDE0NC03MzcuMSwxNzUuNi03NjguNGM2LjctNi42LDE3LjEtNy40LDI0LjctMmM0NS45LDMyLjUsODQuNCwxNjguNSw4NC40LDE2OC41CgljMTEzLjYsNDIxLjgsMTAzLjMsODE3LjksMTAzLjMsODE3LjljMTAuMywzNDQuNy01Ni45LDczMC41LTU2LjksNzMwLjVDMTM0MS45LDIyMjIuMiwxMjY5LjQsMjI4NCwxMjY5LjQsMjI4NHoiLz4KPHBhdGggY2xhc3M9InN0MCIgZD0iTTIyMDAuNyw3MDguNmMtNjcuMi0xMTcuMS01NDYuMSwzMS42LTEwNzAsMzMycy04OTMuNSw2MzguOS04MjYuMyw3NTUuOXM1NDYuMS0zMS42LDEwNzAtMzMyCglTMjI2Ny44LDgyNS42LDIyMDAuNyw3MDguNkwyMjAwLjcsNzA4LjZ6IE0zNjYuNCwxNzgwLjRjLTI1LjctMy4yLTE5LjktMjQuNC0xOS45LTI0LjRjMzEuNi04OS43LDEzMi0xODMuMiwxMzItMTgzLjIKCWMyNDkuNC0yNjguNCw5MTMuOC02MTkuNyw5MTMuOC02MTkuN2M1NDIuNS0yNTIuNCw3MTEuMS0yNDEuOCw3NTMuOC0yMzBjOS4xLDIuNSwxNSwxMS4yLDE0LDIwLjZjLTUuMSw1Ni0xMDQuMiwxNTctMTA0LjIsMTU3CgljLTMwOS4xLDMwOC42LTY1Ny44LDQ5Ni44LTY1Ny44LDQ5Ni44Yy0yOTMuOCwxODAuNS02NjEuOSwzMTQuMS02NjEuOSwzMTQuMUM0NTYsMTgxMi42LDM2Ni40LDE3ODAuNCwzNjYuNCwxNzgwLjRMMzY2LjQsMTc4MC40CglMMzY2LjQsMTc4MC40eiIvPgo8cGF0aCBjbGFzcz0ic3QwIiBkPSJNMjE5OC40LDE4MDAuNGM2Ny43LTExNi44LTMwMC45LTQ1Ni44LTgyMy03NTkuNVMzNzQuNCw1ODcuOCwzMDYuOCw3MDQuN3MzMDAuOSw0NTYuOCw4MjMuMyw3NTkuNQoJUzIxMzAuNywxOTE3LjQsMjE5OC40LDE4MDAuNHogTTM1MS42LDc0OS44Yy0xMC0yMy43LDExLjEtMjkuNCwxMS4xLTI5LjRjOTMuNS0xNy42LDIyNC43LDIyLjYsMjI0LjcsMjIuNgoJYzM1Ny4yLDgxLjMsOTk0LDQ4MC4yLDk5NCw0ODAuMmM0OTAuMywzNDMuMSw1NjUuNSw0OTQuMiw1NzYuOCw1MzcuMWMyLjQsOS4xLTIuMiwxOC42LTEwLjcsMjIuNGMtNTEuMSwyMy40LTE4OC4xLTExLjUtMTg4LjEtMTEuNQoJYy00MjIuMS0xMTMuMi03NTkuNi0zMjAuNS03NTkuNi0zMjAuNWMtMzAzLjMtMTYzLjYtNjAzLjItNDE1LjMtNjAzLjItNDE1LjNjLTIyNy45LTE5MS45LTI0NS0yODUuNC0yNDUtMjg1LjRMMzUxLjYsNzQ5Ljh6Ii8+CjxjaXJjbGUgY2xhc3M9InN0MSIgY3g9IjEyNTAiIGN5PSIxMjUwIiByPSIxMjguNiIvPgo8ZWxsaXBzZSBjbGFzcz0ic3QxIiBjeD0iMTc3Ny4zIiBjeT0iNzU2LjIiIHJ4PSI3NC42IiByeT0iNzcuMiIvPgo8ZWxsaXBzZSBjbGFzcz0ic3QxIiBjeD0iNTUzIiBjeT0iMTAxOC41IiByeD0iNzQuNiIgcnk9Ijc3LjIiLz4KPGVsbGlwc2UgY2xhc3M9InN0MSIgY3g9IjEwOTguMiIgY3k9IjE5NjUiIHJ4PSI3NC42IiByeT0iNzcuMiIvPgo8L3N2Zz4K diff --git a/ci/no-std-check/Cargo.lock b/ci/no-std-check/Cargo.lock index 583c70a256..f23838f273 100644 --- a/ci/no-std-check/Cargo.lock +++ b/ci/no-std-check/Cargo.lock @@ -377,9 +377,9 @@ dependencies = [ [[package]] name = "digest" -version = "0.10.3" +version = "0.10.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f2fb860ca6fafa5552fb6d0e816a69c8e49f0908bf524e30a90d97c85892d506" +checksum = "adfbc57365a37acbd2ebf2b64d7e69bb766e2fea813521ed536f5d0520dcf86c" dependencies = [ "block-buffer 0.10.2", "crypto-common", @@ -480,6 +480,15 @@ dependencies = [ "static_assertions", ] +[[package]] +name = "fixed-hash" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "835c052cb0c08c1acf6ffd71c022172e18723949c8282f2b9f27efbc51e64534" +dependencies = [ + "static_assertions", +] + [[package]] name = "flex-error" version = "0.4.4" @@ -738,13 +747,13 @@ dependencies = [ "ibc-proto", "ics23", "num-traits", - "primitive-types 0.11.1", + "primitive-types 0.12.0", "prost", "safe-regex", "serde", "serde_derive", "serde_json", - "sha2 0.10.2", + "sha2 0.10.6", "subtle-encoding", "tendermint", "tendermint-light-client-verifier", @@ -757,6 +766,7 @@ dependencies = [ [[package]] name = "ibc-proto" version = "0.20.1" +source = "git+https://github.com/hu55a1n1/ibc-proto#e1d570b31e6c36d56db66da22c10386bd97a5886" dependencies = [ "base64", "bytes", @@ -778,7 +788,7 @@ dependencies = [ "hex", "prost", "ripemd", - "sha2 0.10.2", + "sha2 0.10.6", "sha3", ] @@ -800,6 +810,15 @@ dependencies = [ "serde", ] +[[package]] +name = "impl-serde" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ebc88fc67028ae3db0c853baa36269d398d5f45b6982f95549ff5def78c935cd" +dependencies = [ + "serde", +] + [[package]] name = "impl-trait-for-tuples" version = "0.2.2" @@ -1258,21 +1277,21 @@ version = "0.10.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "05e4722c697a58a99d5d06a08c30821d7c082a4632198de1eaa5a6c22ef42373" dependencies = [ - "fixed-hash", + "fixed-hash 0.7.0", "impl-codec", - "impl-serde", + "impl-serde 0.3.2", "scale-info", "uint", ] [[package]] name = "primitive-types" -version = "0.11.1" +version = "0.12.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e28720988bff275df1f51b171e1b2a18c30d194c4d2b61defdacecd625a5d94a" +checksum = "5cfd65aea0c5fa0bfcc7c9e7ca828c921ef778f43d325325ec84bda371bfa75a" dependencies = [ - "fixed-hash", - "impl-serde", + "fixed-hash 0.8.0", + "impl-serde 0.4.0", "uint", ] @@ -1486,7 +1505,7 @@ version = "0.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1facec54cb5e0dc08553501fa740091086d0259ad0067e0d4103448e4cb22ed3" dependencies = [ - "digest 0.10.3", + "digest 0.10.5", ] [[package]] @@ -1696,13 +1715,13 @@ dependencies = [ [[package]] name = "sha2" -version = "0.10.2" +version = "0.10.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "55deaec60f81eefe3cce0dc50bda92d6d8e88f2a27df7c5033b42afeb1ed2676" +checksum = "82e6b795fe2e3b1e845bafcb27aa35405c4d47cdfc92af5fc8d3002f76cebdc0" dependencies = [ "cfg-if", "cpufeatures", - "digest 0.10.3", + "digest 0.10.5", ] [[package]] @@ -1711,7 +1730,7 @@ version = "0.10.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0a31480366ec990f395a61b7c08122d99bd40544fdb5abcfc1b06bb29994312c" dependencies = [ - "digest 0.10.3", + "digest 0.10.5", "keccak", ] @@ -1791,7 +1810,7 @@ dependencies = [ "hash-db", "hash256-std-hasher", "hex", - "impl-serde", + "impl-serde 0.3.2", "lazy_static", "libsecp256k1", "log", @@ -1807,7 +1826,7 @@ dependencies = [ "schnorrkel", "secrecy", "serde", - "sha2 0.10.2", + "sha2 0.10.6", "sp-core-hashing", "sp-debug-derive", "sp-externalities", @@ -2004,7 +2023,7 @@ version = "5.0.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "838ec2a757a8e7b903684a71f649dfbd6449d91e3e5d93979fc8d2ee77d56fee" dependencies = [ - "impl-serde", + "impl-serde 0.3.2", "parity-scale-codec", "ref-cast", "serde", diff --git a/ci/no-std-check/Cargo.toml b/ci/no-std-check/Cargo.toml index 9d089bc647..344b69f345 100644 --- a/ci/no-std-check/Cargo.toml +++ b/ci/no-std-check/Cargo.toml @@ -5,8 +5,8 @@ edition = "2021" resolver = "2" [dependencies] -ibc = { path = "../../crates/modules", default-features = false } -ibc-proto = { path = "../../crates/proto", default-features = false } +ibc = { path = "../../crates/ibc", default-features = false } +ibc-proto = { version = "0.20.1", default-features = false } tendermint = { version = "0.23.9", default-features = false } tendermint-proto = { version = "0.23.9", default-features = false } tendermint-light-client-verifier = { version = "0.23.9", default-features = false } @@ -31,7 +31,5 @@ substrate-std = [ "sp-std/std", ] -# [patch.crates-io] -# tendermint = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" } -# tendermint-proto = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" } -# tendermint-light-client-verifier = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" } +[patch.crates-io] +ibc-proto = { git = "https://github.com/hu55a1n1/ibc-proto" } diff --git a/crates/ibc/Cargo.toml b/crates/ibc/Cargo.toml index d4f4974a39..4b5d607bbf 100644 --- a/crates/ibc/Cargo.toml +++ b/crates/ibc/Cargo.toml @@ -5,7 +5,7 @@ edition = "2021" license = "Apache-2.0" readme = "README.md" keywords = ["blockchain", "consensus", "cosmos", "ibc", "tendermint"] -repository = "https://github.com/informalsystems/ibc-rs" +repository = "https://github.com/cosmos/ibc-rs" authors = ["Informal Systems "] rust-version = "1.60" description = """ @@ -27,7 +27,7 @@ mocks = ["tendermint-testgen", "clock", "std"] [dependencies] # Proto definitions for all IBC-related interfaces, e.g., connections or channels. -ibc-proto = { version = "0.20.1", path = "../proto", default-features = false } +ibc-proto = { version = "0.20.1", default-features = false } ics23 = { version = "=0.8.1", default-features = false, features = ["host-functions"] } time = { version = ">=0.3.0, <0.3.12", default-features = false } serde_derive = { version = "1.0.104", default-features = false } diff --git a/crates/ibc/README.md b/crates/ibc/README.md index 00a29c55dd..1177689e42 100644 --- a/crates/ibc/README.md +++ b/crates/ibc/README.md @@ -1,4 +1,4 @@ -# IBC module +# IBC in Rust [![Crate][crate-image]][crate-link] [![Docs][docs-image]][docs-link] @@ -6,13 +6,10 @@ [![End to End testing][e2e-image]][e2e-link] [![Apache 2.0 Licensed][license-image]][license-link] ![Rust Stable][rustc-image] -![Rust 1.51+][rustc-version] +![Rust 1.60+][rustc-version] -See the [ibc-rs] repo root for more detailed information on how this crate can be used. - - -Implementation of the Inter-Blockchain Communication Protocol ([IBC]) module. +Implementation of the Inter-Blockchain Communication Protocol ([IBC]) in Rust. ## Documentation @@ -60,17 +57,17 @@ Unless required by applicable law or agreed to in writing, software distributed [docs-image]: https://docs.rs/ibc/badge.svg [docs-link]: https://docs.rs/ibc/ -[build-image]: https://github.com/informalsystems/ibc-rs/workflows/Rust/badge.svg -[build-link]: https://github.com/informalsystems/ibc-rs/actions?query=workflow%3ARust -[e2e-image]: https://github.com/informalsystems/ibc-rs/workflows/End%20to%20End%20testing/badge.svg -[e2e-link]: https://github.com/informalsystems/ibc-rs/actions?query=workflow%3A%22End+to+End+testing%22 +[build-image]: https://github.com/cosmos/ibc-rs/workflows/Rust/badge.svg +[build-link]: https://github.com/cosmos/ibc-rs/actions?query=workflow%3ARust +[e2e-image]: https://github.com/cosmos/ibc-rs/workflows/End%20to%20End%20testing/badge.svg +[e2e-link]: https://github.com/cosmos/ibc-rs/actions?query=workflow%3A%22End+to+End+testing%22 [license-image]: https://img.shields.io/badge/license-Apache2.0-blue.svg -[license-link]: https://github.com/informalsystems/ibc-rs/blob/master/LICENSE +[license-link]: https://github.com/cosmos/ibc-rs/blob/main/LICENSE [rustc-image]: https://img.shields.io/badge/rustc-stable-blue.svg -[rustc-version]: https://img.shields.io/badge/rustc-1.51+-blue.svg +[rustc-version]: https://img.shields.io/badge/rustc-1.60+-blue.svg [//]: # (general links) -[ibc-rs]: https://github.com/informalsystems/ibc-rs +[ibc-rs]: https://github.com/cosmos/ibc-rs [IBC]: https://github.com/cosmos/ibc diff --git a/crates/ibc/src/lib.rs b/crates/ibc/src/lib.rs index b3a4eec68c..dfc0eb82c5 100644 --- a/crates/ibc/src/lib.rs +++ b/crates/ibc/src/lib.rs @@ -37,12 +37,12 @@ //! `Relayer` contains utilities for testing the `ibc` crate against the [Hermes IBC relayer][relayer-repo]. It acts //! as scaffolding for gluing the `ibc` crate with Hermes for testing purposes. //! -//! [core]: https://github.com/informalsystems/ibc-rs/tree/master/modules/src/core -//! [clients]: https://github.com/informalsystems/ibc-rs/tree/master/modules/src/clients -//! [applications]: https://github.com/informalsystems/ibc-rs/tree/master/modules/src/applications +//! [core]: https://github.com/cosmos/ibc-rs/tree/main/crates/ibc/src/core +//! [clients]: https://github.com/cosmos/ibc-rs/tree/main/crates/ibc/src/clients +//! [applications]: https://github.com/cosmos/ibc-rs/tree/main/crates/ibc/src/applications //! [ics-standards]: https://github.com/cosmos/ibc#interchain-standards -//! [relayer]: https://github.com/informalsystems/ibc-rs/tree/master/modules/src/relayer -//! [relayer-repo]: https://github.com/informalsystems/ibc-rs/tree/master/relayer +//! [relayer]: https://github.com/cosmos/ibc-rs/tree/main/crates/ibc/src/relayer +//! [relayer-repo]: https://github.com/informalsystems/ibc-rs/tree/main/relayer extern crate alloc; diff --git a/crates/ibc/src/relayer/mod.rs b/crates/ibc/src/relayer/mod.rs index e88996bcd5..336ae18317 100644 --- a/crates/ibc/src/relayer/mod.rs +++ b/crates/ibc/src/relayer/mod.rs @@ -1,5 +1,5 @@ //! Utilities for testing the `ibc` crate against the [Hermes IBC relayer][relayer-repo]. //! -//! [relayer-repo]: https://github.com/informalsystems/ibc-rs/tree/master/relayer +//! [relayer-repo]: https://github.com/informalsystems/ibc-rs/tree/main/relayer pub mod ics18_relayer; diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 0000000000..48af14dfe6 --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,30 @@ +# Architecture Decision Records (ADR) + +This is a location to record all high-level architecture decisions in the IBC-RS project. + +You can read more about the ADR concept in this [blog post](https://product.reverb.com/documenting-architecture-decisions-the-reverb-way-a3563bb24bd0#.78xhdix6t). + +An ADR should provide: + +- Context on the relevant goals and the current state +- Proposed changes to achieve the goals +- Summary of pros and cons +- References +- Changelog + +Note the distinction between an ADR and a spec. The ADR provides the context, intuition, reasoning, and +justification for a change in architecture, or for the architecture of something +new. The spec is much more compressed and streamlined summary of everything as +it is or should be. + +If recorded decisions turned out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match. + +Note the context/background should be written in the present tense. + +To suggest an ADR, please make use of the [ADR template](./adr-template.md) provided. + +## Table of Contents + +| ADR \# | Description | Status | +|-----------------------------------------------------------|-------------------------------------------------------|----------| + diff --git a/docs/architecture/adr-template.md b/docs/architecture/adr-template.md new file mode 100644 index 0000000000..28a5ecfbbc --- /dev/null +++ b/docs/architecture/adr-template.md @@ -0,0 +1,36 @@ +# ADR {ADR-NUMBER}: {TITLE} + +## Changelog +* {date}: {changelog} + +## Context + +> This section contains all the context one needs to understand the current state, and why there is a problem. It should be as succinct as possible and introduce the high level idea behind the solution. +## Decision + +> This section explains all of the details of the proposed solution, including implementation details. +It should also describe affects / corollary items that may need to be changed as a part of this. +If the proposed change will be large, please also indicate a way to do the change to maximize ease of review. +(e.g. the optimal split of things to do between separate PR's) + +## Status + +> A decision may be "proposed" if it hasn't been agreed upon yet, or "accepted" once it is agreed upon. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to its replacement. + +{Deprecated|Proposed|Accepted} + +## Consequences + +> This section describes the consequences, after applying the decision. All consequences should be summarized here, not just the "positive" ones. + +### Positive + +### Negative + +### Neutral + +## References + +> Are there any relevant PR comments, issues that led up to this, or articles referrenced for why we made the given design choice? If so link them here! + +* {reference link}