Skip to content

Commit

Permalink
Refactoring web docs
Browse files Browse the repository at this point in the history
  • Loading branch information
csordasmarton committed Apr 1, 2019
1 parent c5512e8 commit e8b36f7
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 31 deletions.
28 changes: 14 additions & 14 deletions docs/web/api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ For example:

https://example.com:8001/Default/v6.0/CodeCheckerService

Executing `make thrift` in the main folder of CodeChecker will automatically
Executing `make thrift` in the web folder of CodeChecker will automatically
build each API version to the `build/` dir.

## How to add new API versions <a name="how-to-add-new-api-versions"></a>
Expand All @@ -57,11 +57,11 @@ already existing functions, only extend the API:

1. After implementing the changes to the existing API files and handlers,
you need to increase the `SUPPORTED_VERSIONS` tag in
`libcodechecker/version.py`. This dict stores for each major version, which
is the highest supported minor version. In this case, simply increase the
number by `1`.
2. Change the `www/scripts/version.js` file to represent the newest version,
e.g. `6.1`.
`codechecker_web/shared/version.py`. This dict stores for each major
version, which is the highest supported minor version. In this case, simply
increase the number by `1`.
2. Change the `web/server/www/scripts/version.js` file to represent the newest
version, e.g. `6.1`.

### Major API changes <a name="major-api-changes"></a>

Expand All @@ -75,15 +75,15 @@ copy of the previous version's API to a new folder, e.g. `v7`.
1. The new API definition (`thrift`) files must have the `namespace` tag
appropriately suffixed, e.g. `_v7`.
2. Register a new *major* version in the `SUPPORTED_VERSIONS` dict in
`libcodechecker/version.py`, but do **NOT** change the previous major
version's setting. The first *minor* version for every *major* version is `0`,
i.e. `7.0`.
3. Change the `www/scripts/version.js` to use the newest API, `7.0` in this
case.
4. Change the imports used in `www/scripts/<site>/<site>.js` (`<site>` is
`codecheckerviewer` or `productlist`) to load the API client from the new
`codechecker_web/shared/version.py`, but do **NOT** change the previous
major version's setting. The first *minor* version for every *major* version
is `0`, i.e. `7.0`.
3. Change the `server/www/scripts/version.js` to use the newest API, `7.0` in
this case.
4. Change the imports used in `server/www/scripts/<site>/<site>.js` (`<site>`
is `codecheckerviewer` or `productlist`) to load the API client from the new
version. Do the same with the Python code everywhere (including the tests)
where API clients are used (`libcodechecker/libclient`).
where API clients are used (`client/codechecker_client`).
5. Implement requesting actions via the new API in the command-line and the
Web client.
6. In the server, implement the API handlers for the new version **as
Expand Down
41 changes: 24 additions & 17 deletions docs/web/db_schema_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ http://alembic.readthedocs.org/en/latest/autogenerate.html#what-does-autogenerat

# Updating configuration database schema

Config database schema scripts can be found under the `config_db_migrate` directory.
Config database schema scripts can be found under the `config_db_migrate`
directory.

## Automatic migration script generation (Online)

Expand All @@ -26,7 +27,8 @@ version.

### **Step 1**: Update the database model

The configuration database schema file can be found here: `libcodechecker/server/config_db_model.py`
The configuration database schema file can be found here:
`server/codechecker_server/database/config_db_model.py`

### **Step 2**: Check the alembic.ini configuration settings

Expand All @@ -40,9 +42,10 @@ Edit the sqlalchemy.url option in [alembic.ini](
`alembic --name config_db revision --autogenerate -m "Change description"`

### **Step 4**: Check the generated scripts
The new migration script `config_db_migrate/versions/{hash}_change_description.py` is
generated. **You must always check the generated script because sometimes it
isn't correct.**
The new migration script
`config_db_migrate/versions/{hash}_change_description.py` is generated.
**You must always check the generated script because sometimes it isn't
correct.**

### **Step 5**: Run all test cases.

Expand All @@ -57,11 +60,13 @@ Don't forget to commit the migration script with your other changes.

## Automatic migration script generation (Online)

A Codechecker server should be started and a product should be configured with a previous database schema version.
A Codechecker server should be started and a product should be configured with
a previous database schema version.

### **Step 1**: Update the database model

The run database schema file can be found here: `libcodechecker/server/run_db_model.py`
The run database schema file can be found here:
`server/codechecker_server/database/run_db_model.py`

### **Step 2**: Check alembic.ini configuration

Expand Down Expand Up @@ -94,8 +99,9 @@ migration script using `alembic revision`:

`alembic --name run_db revision -m "Change description"`

The new file `db_migrate/versions/{hash}_change_description.py` is generated. This
file contains an empty `upgrade` and a `downgrade` function.
The new file
`server/codechecker_server/migrations/report/versions/{hash}_change_description.py`
is generated. This file contains an empty `upgrade` and a `downgrade` function.

The empty `upgrade` and `downgrade` should be written by hand.

Expand All @@ -122,22 +128,23 @@ previous version and there will be no data loss.
### Migration at server start

Schema migration can be done at server start. The database for the config
and product databases will be automatically checked. If there are databases which can
be upgraded you will be asked if you want to upgrade the schema to the latest
version.
and product databases will be automatically checked. If there are databases
which can be upgraded you will be asked if you want to upgrade the schema to
the latest version.

NOTE: Before running the migration you should make a full backup of your
config and product databases!

The config database location will be printed first at the server start.
Migration of the config database is done independently from the product databases.
The product database locations can be viewed with the `CodeChecker server
--db-status all` command.
Migration of the config database is done independently from the product
databases. The product database locations can be viewed with the
`CodeChecker server --db-status all` command.

## Checking if migration will be required.

Running the `CodeChecker server --db-status all` command with the new CodeChecker
release will show you if database upgrade is needed for the new release.
Running the `CodeChecker server --db-status all` command with the new
CodeChecker release will show you if database upgrade is needed for the new
release.

NOTE: Use the same arguments which were used to start the server to check
the status. It is required to find the used configuration database.
Expand Down

0 comments on commit e8b36f7

Please sign in to comment.