Improving the quick start documentation #52
Conversation
SdgJlbl
requested review from
ewjoachim,
mgu and
samuelhamard
as code owners
Codecov Report
@@ Coverage Diff @@
## master #52 +/- ##
=======================================
Coverage 56.35% 56.35%
=======================================
Files 14 14
Lines 598 598
Branches 81 81
=======================================
Hits 337 337
Misses 254 254
Partials 7 7
Continue to review full report at Codecov.
|
docs/quickstart.rst
Outdated
| @@ -1,6 +1,68 @@ | |||
| Quickstart | |||
| ========== | |||
|
|
|||
| Use *septentrion* as your migration tool in 2 easy steps: | |||
| 1. Write your migrations. | |||
| 2. Run your migrations. | |||
There was a problem hiding this comment.
- Draw the rest of the owl :D
(note: I was the one writing this initially)
README.rst
Outdated
| │ ├── fixtures_0.1.sql | ||
| │ └── fixtures_1.0.sql | ||
| └── schemas | ||
| └── schema_0.1.sql |
There was a problem hiding this comment.
We could prune the tree a bit. I'm not sure it needs to be this long to understand.
(We could skip the fixtures too)
| The final version you target is a required argument (it might change in the future). | ||
|
|
||
| # TODO : do we want to add something about dry-run here? | ||
|
|
There was a problem hiding this comment.
Can we put a conclusion sentence here, summarizing what the user did (congratulations could be nice too)
|
Nicely done, a very successful start. Congratulations, @SdgJlbl ! |
|
|
||
| - Either your environment variables `PGHOST`, `PGPORT` and `PGUSER` are properly set. | ||
| - Or you can set the environment variables `SEPTENTRION_HOST`, `SEPTENTRION_PORT`, `SEPTENTRION_USERNAME`. | ||
| - configuration file `septentrion.ini` |
There was a problem hiding this comment.
I feel like this bullet point is not done :)
There was a problem hiding this comment.
WIP commit is WIP indeed :D
|
|
||
| .. code-block:: console | ||
|
|
||
| [VERSION]-[MIGRATION]-[ORDER]-[TYPE].sql |
There was a problem hiding this comment.
An example would be great I think.
There was a problem hiding this comment.
Same here. All of the "how-to" content has been put there hastily, but we'll get a better look at it later.
|
|
||
| .. code-block:: console | ||
|
|
||
| $ septentrion --target-version 1.0 migrate |
There was a problem hiding this comment.
We currently can't run the first migration wthout a schema and a version. And the schema isn't visible in the show-migrations output :-(
There was a problem hiding this comment.
Related issue for discussion #54
Co-authored-by: samuelhamard <[email protected]>
SdgJlbl
force-pushed
the
improve-quickstart
branch
from
b66529b
to
691a7de
Compare
SdgJlbl
changed the title
This is a first draft concerning the quick start guide in documentation.
I have some questions (as "comments") in the rst. I'm struggling a bit with the level of details we want to provide here (minimal I guess, but I'm not familiar enough with SQL migration to know how much is needed).
Comments welcome :)
Stuff remaining to do:
Successful PR Checklist: