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

chore(docs): improve upgrade readme #2070

Merged
merged 1 commit into from
Sep 4, 2024
Merged

chore(docs): improve upgrade readme #2070

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

### ⚠ BREAKING CHANGES

> [!NOTE]
> The client version number is synchronized with the API's version number, necessitating a major version bump. This does _not_ require DB restore.

* refactor from express to fastify (#2045)
* refactor from Express to Fastify

Expand Down
14 changes: 7 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@

### Local

This service requires `postgres`, `stacks-node`, `bitcoind`, and a few other components in order to run.
This service requires `postgres`, `stacks-node`, `bitcoind`, and a few other components in order to run.
The [`clarinet`](https://github.com/hirosystems/clarinet) project provides an easy way to spin up the API and all these services:
> clarinet devnet - a local standalone development environment that simulates Bitcoin, Stacks node and other helpful components, similar to a staging environment.

Get started at https://docs.hiro.so/clarinet/getting-started
Get started at https://docs.hiro.so/clarinet/getting-started

### Production

Expand All @@ -36,7 +36,7 @@ Check to see if the server started successfully by visiting http://localhost:399

## Local Development

To run the server, run `npm run dev:integrated`, which uses docker-compose to deploy the service dependencies (e.g., PostgreSQL, Stacks core node, etc.).
To run the server, run `npm run dev:integrated`, which uses docker-compose to deploy the service dependencies (e.g., PostgreSQL, Stacks core node, etc.).

You'll have a server on port 3999.

Expand All @@ -52,7 +52,7 @@ We recommend running the API database on PostgreSQL version 14 or newer for opti

## Upgrading

If upgrading the API to a new major version (e.g., `3.0.0` to `4.0.0`), then the Postgres database from the previous version will not be compatible, and the process will fail to start.
If upgrading the API to a new major version (e.g., `3.0.0` to `4.0.0`), then the Postgres database from the previous version will likely be incompatible, and the process will fail to start. However, in some cases, the major versions are for client library changes (which are synced with the api version number). Check the changelog if you're unclear.

[Event Replay](#event-replay) must be used when upgrading major versions. Follow the event replay [instructions](#event-replay-instructions) below. Failure to do so will require wiping the Stacks Blockchain chain state data and the API Postgres database and re-syncing from scratch.

Expand Down Expand Up @@ -170,7 +170,7 @@ To run the new event-replay, please follow the instructions at [stacks-event-rep
* `archival` (default): The process will import and ingest *all* blockchain events that have
happened since the first block.
* `pruned`: The import process will ignore some prunable events (mempool, microblocks) until the
import block height has reached `chain tip - 256` blocks. This saves considerable
import block height has reached `chain tip - 256` blocks. This saves considerable
time during import but sacrifices some historical data. You can use this mode if you're mostly
interested in running an API that prioritizes real-time information.

Expand All @@ -189,7 +189,7 @@ Please **do not** use the issue tracker for personal support requests or to ask
Development of this product happens in the open on GitHub, and we are grateful to the community for contributing bug fixes and improvements. Read below to learn how you can take part in improving the product.

### Code of Conduct
Please read our [Code of Conduct](../../../.github/blob/main/CODE_OF_CONDUCT.md) since we expect project participants to adhere to it.
Please read our [Code of Conduct](../../../.github/blob/main/CODE_OF_CONDUCT.md) since we expect project participants to adhere to it.

### Contributing Guide

Expand All @@ -199,7 +199,7 @@ Hiro welcomes all contributions to Hiro documentation. These contributions come

Bugs, feature requests, and development-related questions should be directed to our [GitHub issues tracker](https://github.com/hirosystems/stacks-blockchain-api/issues/new).

If reporting a bug, try to provide as much context as possible and anything else that might be relevant to the describe the issue. If possible include a simple test case that we can use to reproduce the problem on our own.
If reporting a bug, try to provide as much context as possible and anything else that might be relevant to the describe the issue. If possible include a simple test case that we can use to reproduce the problem on our own.

For feature requests, please explain what you're trying to do, and how the requested feature would be a complement to the project.

Expand Down
Loading