From 4fd11a4becb5b27380ae3edcbbdcc75c9f9237db Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 12 Dec 2022 14:35:06 -0800 Subject: [PATCH] Document install script (#952) --- README.md | 129 ++++++-------------------------- docs/src/SUMMARY.md | 5 +- docs/src/contributing.md | 84 +++++++++++++++++++++ docs/src/guides/inscriptions.md | 6 ++ src/subcommand/server.rs | 15 +++- 5 files changed, 126 insertions(+), 113 deletions(-) create mode 100644 docs/src/contributing.md diff --git a/README.md b/README.md index a77b1f5e79..184e106d8e 100644 --- a/README.md +++ b/README.md @@ -18,95 +18,24 @@ where the project is and where it's going. Join [the Discord server](https://discord.gg/87cjuz4FYg) to chat with fellow ordinal degenerates. -Contributing +Installation ------------ -### Suggested Steps - -1. Find an issue you want to work on. -2. Figure out what would be a good first step towards resolving the issue. This - could be in the form of code, research, a proposal, or suggesting that it be - closed, if it's out of date or not a good idea in the first place. -3. Comment on the issue with an outline of your suggested first step, and - asking for feedback. Of course, you can dive in and start writing code or - tests immediately, but this avoids potentially wasted effort, if the issue - is out of date, not clearly specified, blocked on something else, or - otherwise not ready to implement. -4. If the issue requires a code change or bugfix, open a draft PR with tests, - and ask for feedback. This makes sure that everyone is on the same page - about what needs to be done, or what the first step in solving the issue - should be. Also, since tests are required, writing the tests first makes it - easy to confirm that the change can be tested easily. -5. Mash the keyboard randomly until the tests pass, and refactor until the code - is ready to submit. -6. Mark the PR as ready to review. -7. Revise the PR as needed. -8. And finally, mergies! - -### Advice - -#### Start small - -Small changes will allow you to make an impact -quickly, and if you take the wrong tack, you won't have wasted much time. - -Ideas for small issues: -- Add a new test or test case that increases test coverage -- Add or improve documentation -- Find an issue that needs more research, and do that research and summarize it - in a comment -- Find an out-of-date issue and comment that it can be closed -- Find an issue that shouldn't be done, and provide constrictive feedback - detailing why you think that is the case - -#### Merge early and often - -Break up large tasks into multiple smaller steps that individually make -progress. If there's a bug, you can open a PR that adds a failing ignored test. -This can be merged, and the next step can be to fix the bug and unignore the -test. Do research or testing, and report on your results. Break a feature into -small sub-features, and implement them one at a time. - -Figuring out how to break down a larger PR into smaller PRs where each can be -merged is a art form well-worth practicing. The hard part is that each PR must -itself be an improvement. - -I strive to follow this advice myself, and am always better off when I do. - -Small changes are fast to write, review, and merge, which is much more fun than -laboring over a single giant PR that takes forever to write, review, and merge. -Small changes don't take much time, so if you need to stop working on a small -change, you won't have wasted much time as compared to a larger change that -represents many hours of work. Getting a PR in quickly improves the project a -little bit immediately, instead of having to wait a long time for larger -improvement. Small changes are less likely to accumulate merge conflict. As the -Athenians said: *The fast commit what they will, the slow merge what they -must.* - -#### Get help - -If you're stuck for more than 15 minutes, ask for help, like a Rust Discord, -Stack Exchange, or in a project issue or discussion. - -#### Practice hypothesis-driven debugging - -Formulate a hypothesis as to what is causing the problem. Figure out how to -test that hypothesis. Perform that tests. If it works, great, you fixed the -issue or now you know how to fix the issue. If not, repeat with a new -hypothesis. - -#### Pay attention to error messages - -Read all error messages, and don't tolerate warnings. - -### Copyright - -`ord` is licensed under the CC0, a no-strings-attached public domain dedication -and fallback license. Your changes must be licensed under the CC0, without any -additional terms or conditions - -Running `ord` -------------- +`ord` is written in Rust and can be built from +[source](https://github.com/casey/ord). Pre-built binaries are available on the +[releases page](https://github.com/casey/ord/releases). + +You can install the latest pre-built binary from the command line with: + +```sh +curl --proto '=https' --tlsv1.2 -fsLS https://ordinals.com/install.sh | bash -s +``` + +Once `ord` is installed, you should be able to run `ord --version` on the +command line. + +Syncing +------- `ord` requires a synced `bitcoind` node with `-txindex` to build the index of ordinal locations. `ord` communicates with `bitcoind` via RPC. @@ -119,29 +48,13 @@ If `bitcoind` is not on mainnet, is not run by the same user, has a non-default datadir, or a non-default port, you'll need to pass additional flags to `ord`. See `ord --help` for details. -### Minimum System Requirements - -Building the `ord` index is memory-intensive. An `ord` instance running on a -reasonably powerful system with 64 GiB of RAM and a fully-synced, -locally-hosted Bitcoin Core node can build the index in under 24 hours. +Logging +-------- -An `ord` instance running on a system with less than 64 GiB of RAM will take -much longer to build the index, with some users reporting sync times of two -weeks or more. - -A this point in development, the format of the `ord` index is changing rapidly, -so be prepared to delete and re-sync the index. - -### Logging - -`ord` uses [env_logger](https://docs.rs/env_logger/latest/env_logger/). Set the `RUST_LOG` environment variable in order to turn on logging. For example, run the server and show `info`-level log messages and above: +`ord` uses [env_logger](https://docs.rs/env_logger/latest/env_logger/). Set the +`RUST_LOG` environment variable in order to turn on logging. For example, run +the server and show `info`-level log messages and above: ``` $ RUST_LOG=info cargo run server ``` - -Reorgs ------- - -Currently, reorganizations are detected but not handled. After reorgs happen, -you'll need to delete `index.redb` and start over. diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 75400b77b4..6cf65c926b 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -1,15 +1,12 @@ # Summary - [Introduction](introduction.md) - - [Overview](overview.md) - [FAQ](faq.md) - +- [Contributing](contributing.md) - [Guides](guides.md) - [Explorer](guides/explorer.md) - [Inscriptions](guides/inscriptions.md) - [Ordinal Hunting](guides/ordinal-hunting.md) - - [Bounties](bounties.md) - [Bounty 0: 100,000 sats Claimed!](bounty/0.md) - [Bounty 1: 200,000 sats Claimed!](bounty/1.md) diff --git a/docs/src/contributing.md b/docs/src/contributing.md new file mode 100644 index 0000000000..bfb24f4e97 --- /dev/null +++ b/docs/src/contributing.md @@ -0,0 +1,84 @@ +Contributing to `ord` +===================== + +Suggested Steps +--------------- + +1. Find an issue you want to work on. +2. Figure out what would be a good first step towards resolving the issue. This + could be in the form of code, research, a proposal, or suggesting that it be + closed, if it's out of date or not a good idea in the first place. +3. Comment on the issue with an outline of your suggested first step, and + asking for feedback. Of course, you can dive in and start writing code or + tests immediately, but this avoids potentially wasted effort, if the issue + is out of date, not clearly specified, blocked on something else, or + otherwise not ready to implement. +4. If the issue requires a code change or bugfix, open a draft PR with tests, + and ask for feedback. This makes sure that everyone is on the same page + about what needs to be done, or what the first step in solving the issue + should be. Also, since tests are required, writing the tests first makes it + easy to confirm that the change can be tested easily. +5. Mash the keyboard randomly until the tests pass, and refactor until the code + is ready to submit. +6. Mark the PR as ready to review. +7. Revise the PR as needed. +8. And finally, mergies! + +Start small +----------- + +Small changes will allow you to make an impact +quickly, and if you take the wrong tack, you won't have wasted much time. + +Ideas for small issues: +- Add a new test or test case that increases test coverage +- Add or improve documentation +- Find an issue that needs more research, and do that research and summarize it + in a comment +- Find an out-of-date issue and comment that it can be closed +- Find an issue that shouldn't be done, and provide constrictive feedback + detailing why you think that is the case + +Merge early and often +--------------------- + +Break up large tasks into multiple smaller steps that individually make +progress. If there's a bug, you can open a PR that adds a failing ignored test. +This can be merged, and the next step can be to fix the bug and unignore the +test. Do research or testing, and report on your results. Break a feature into +small sub-features, and implement them one at a time. + +Figuring out how to break down a larger PR into smaller PRs where each can be +merged is a art form well-worth practicing. The hard part is that each PR must +itself be an improvement. + +I strive to follow this advice myself, and am always better off when I do. + +Small changes are fast to write, review, and merge, which is much more fun than +laboring over a single giant PR that takes forever to write, review, and merge. +Small changes don't take much time, so if you need to stop working on a small +change, you won't have wasted much time as compared to a larger change that +represents many hours of work. Getting a PR in quickly improves the project a +little bit immediately, instead of having to wait a long time for larger +improvement. Small changes are less likely to accumulate merge conflict. As the +Athenians said: *The fast commit what they will, the slow merge what they +must.* + +Get help +-------- + +If you're stuck for more than 15 minutes, ask for help, like a Rust Discord, +Stack Exchange, or in a project issue or discussion. + +Practice hypothesis-driven debugging +------------------------------------ + +Formulate a hypothesis as to what is causing the problem. Figure out how to +test that hypothesis. Perform that tests. If it works, great, you fixed the +issue or now you know how to fix the issue. If not, repeat with a new +hypothesis. + +Pay attention to error messages +------------------------------- + +Read all error messages and don't tolerate warnings. diff --git a/docs/src/guides/inscriptions.md b/docs/src/guides/inscriptions.md index 0019bf0a60..3e1d33422c 100644 --- a/docs/src/guides/inscriptions.md +++ b/docs/src/guides/inscriptions.md @@ -110,6 +110,12 @@ The `ord` utility is written in Rust and can be built from [source](https://github.com/casey/ord). Pre-built binaries are available on the [releases page](https://github.com/casey/ord/releases). +You can install the latest pre-built binary from the command line with: + +```sh +curl --proto '=https' --tlsv1.2 -fsLS https://ordinals.com/install.sh | bash -s +``` + Once `ord` is installed, you should be able to run `ord --version` on the command line. diff --git a/src/subcommand/server.rs b/src/subcommand/server.rs index 75bbb94303..5f1b01f68b 100644 --- a/src/subcommand/server.rs +++ b/src/subcommand/server.rs @@ -150,14 +150,15 @@ impl Server { let router = Router::new() .route("/", get(Self::home)) + .route("/block-count", get(Self::block_count)) .route("/block/:query", get(Self::block)) .route("/bounties", get(Self::bounties)) .route("/clock", get(Self::clock)) .route("/faq", get(Self::faq)) .route("/favicon.ico", get(Self::favicon)) - .route("/block-count", get(Self::block_count)) .route("/input/:block/:transaction/:input", get(Self::input)) .route("/inscription/:txid", get(Self::inscription)) + .route("/install.sh", get(Self::install_script)) .route("/ordinal/:ordinal", get(Self::ordinal)) .route("/output/:output", get(Self::output)) .route("/range/:start/:end", get(Self::range)) @@ -416,6 +417,10 @@ impl Server { ) } + async fn install_script() -> Redirect { + Redirect::to("https://raw.githubusercontent.com/casey/ord/master/install.sh") + } + async fn block( Extension(chain): Extension, Extension(index): Extension>, @@ -941,6 +946,14 @@ mod tests { ); } + #[test] + fn install_sh_redirects_to_github() { + TestServer::new().assert_redirect( + "/install.sh", + "https://raw.githubusercontent.com/casey/ord/master/install.sh", + ); + } + #[test] fn bounties_redirects_to_docs_site() { TestServer::new().assert_redirect("/bounties", "https://docs.ordinals.com/bounty/");