search

rethinkdb / horizon-docs

Other
24 stars 36 forks source link

Horizon 2.0 docs checklist #104

Open dalanmiller opened 8 years ago

dalanmiller commented 8 years ago

With the impending release of Horizon 2.0 we need to make sure our bases are covered in the docs:

Please also review @deontologician + @Tryneus

Additional things before Horizon 2.0 beta release is ready that are currently incomplete:

deontologician commented 8 years ago

Also @Tryneus is getting rid of the horizon_internal table, and indexes will be named differently: rethinkdb/horizon#650

chipotle commented 8 years ago

When you say "make it clear engine.io is no longer used," what do you need to have mentioned? (AFAICT we don't mention "engine.io" anywhere in the current set of docs.)

dalanmiller commented 8 years ago

When you say "make it clear engine.io is no longer used," what do you need to have mentioned? (AFAICT we don't mention "engine.io" anywhere in the current set of docs.)

That's all I wanted to accomplish there @chipotle, just wanted to make sure there weren't any loose mentions hanging around.

deontologician commented 8 years ago

I added another bullet for checking for references to client logging functions. I doubt they were documented, but they were removed so we should make sure

dalanmiller commented 8 years ago

Where are the aggregation queries documented? (I wish Github told us who checked which checkmarks)

chipotle commented 8 years ago

They're in the commit that closes #99, which is merged into the horizon-2.0 docs branch. I'll do a PR for that whole branch to close this ticket.

For https://github.com/rethinkdb/horizon/pull/636 is there a way for the user to set the write retry timeout?

dalanmiller commented 8 years ago

@Tryneus ^^

Tryneus commented 8 years ago

@chipotle - currently there is no client support for it, it's just an option available in the protocol.

chipotle commented 8 years ago

Okay, so is there a timeout enabled in Horizon 2.0? I just want to know if I should be deleting the "Horizon will not automatically retry writes that have version conflicts" line from the limitations document, and adding something to the FAQ saying "Horizon will automatically retry writes for ___ seconds." :)

chipotle commented 8 years ago

With respect to "Remove references to the client logging functions (if any)," does that mean that the debug option needs to be removed? (There's nothing in the docs about .enableLogging as a method.)

deontologician commented 8 years ago

@chipotle the debug option in the cli still works, and any logging in the server still works. You used to be able to do Horizon.enableLogging() to get console messages when sending or receiving on the client. It was unlikely anything was documented I just wanted to make sure

intellix commented 8 years ago

This was fixed/merged: https://github.com/rethinkdb/horizon/issues/498. Is there any migration info for new table names required for the docs?

dalanmiller commented 8 years ago

Nice work all 👍 🚢

dalanmiller commented 8 years ago

One more @chipotle:

  • [ ] Instruct users that collections cannot start with hz_, this will result in an error (limitations page)
dalanmiller commented 8 years ago

@danielmewes added more to the check list from our discussion ^^

danielmewes commented 8 years ago

https://github.com/rethinkdb/horizon/issues/704 has a list of the corresponding issues for the missing pieces in the main Horizon tracker.

chipotle commented 8 years ago

A couple questions about some of those pieces:

danielmewes commented 8 years ago

@chipotle hz schema apply does not convert the schema file itself. If you want to get a new schema file that uses the current format, you have to apply it first, and then use hz schema save to export the schema in the new format. The only difference for the schema file is how indexes are defined (currently a single string that contains all the indexed fields separated by underscores, starting with 2.0 a structure with multiple fields - details pending).

hz migrate works on the Horizon metadata that's stored in RethinkDB. If you have an existing data set for your Horizon application in RethinkDB, it will convert the corresponding metadata, so you can keep using the same RethinkDB database and don't lose any data.

For the upgrade from 1.1 to 2.0 specifically, it will:

It is indeed what you should run to get over the error from hz serve when running on a database with old metadata.

danielmewes commented 8 years ago

One more thing, which I think we forgot about: There are new rdb_timeout, rdb_user and rdb_password options for the config.toml file, the CLI commands, and the Horizon server constructor. See the first post in https://github.com/rethinkdb/horizon/pull/507 .

deontologician commented 8 years ago
danielmewes commented 8 years ago

@chipotle The new format for specifying an index in the schema.toml file for hz schema apply: https://github.com/rethinkdb/horizon/issues/706#issuecomment-238413049

intellix commented 8 years ago

An example with syntax similar to how the current documentation (http://horizon.io/docs/permissions/#configuring) tells you how to create indexes:

[collections.markets]
indexes = [
  'hz_["event_id"]',
  'hz_["event_id", "name"]'
]

first is a single index, second is a composite index

danielmewes commented 8 years ago

@intellix Thanks for the example. Your example is essentially using the old schema.toml syntax for defining indexes (where each index is simply described by a string), though with the new Horizon 2.0 naming scheme. We are actually making the index definition more structured, see the example I linked above: https://github.com/rethinkdb/horizon/issues/706#issuecomment-238413049

I think your syntax will no longer work for the final Horizon 2.0 hz schema apply tool actually. If will be able to read Horizon 1.x index definitions for backwards compatibility, but since your definition is a mixture of Horizon 1.x specifications and the Horizon 2.x index naming scheme, I think the tool will probably get confused and might reject these.

doefler commented 8 years ago

Hi I just did npm install -g horizon@2.0.0-beta-5 Now I am trying to run hz migrate which is not working for me. I am running the command from the my project folder.

I have tried a lot of variations which haven't worked for me. Can you point out what I am doing wrong:

hz migrate hz migrate myhorizonapp hz migrate --project-name myhorizonapp hz migrate -n myhorizonapp hz migrate -n "myhorizonapp" hz migrate "myhorizonapp" hz migrate ./ hz migrate .hz/config.toml hz migrate .hz/ hz migrate .

Errors I got:

/Users/username/.nvm/versions/node/v4.2.1/lib/node_modules/horizon/src/migrate.js:119 throw new Error('No project_name given'); ^

/Users/username/.nvm/versions/node/v4.2.1/lib/node_modules/horizon/nodemodules/toml/lib/parser.js:3946 throw peg$buildException(null, peg$maxFailExpected, peg$maxFailPos); ^ SyntaxError: Expected "#", "E", "\n", "\r", "", "e", [ \t] or [0-9] but "." found.

Thank you.

danielmewes commented 8 years ago

@doefler This issue is about the documentation for Horizon 2.0. The issue you're running into looks like an actual issue with the hz migrate command. Would you mind opening a new issue about this in https://github.com/rethinkdb/horizon/issues ?

doefler commented 8 years ago

@danielmewes thank you for responding. I will open a new issue right away. Since I am not able to run ´hz serve´ without migrating, do you have any ideas on how I can work around it until the migrate tool works?

deontologician commented 8 years ago

The --config option is no longer accepted on any cli commands. Your config files must reside in ${project_dir}/.hz (so secrets.toml, config.toml and schema.toml)