search

php-telegram-bot / docs

[WIP] Documentation of the PHP Telegram Bot
MIT License
1 stars 6 forks source link

Split Vagrantfile shell provisioning to separate file for easier editing #3

Open maxiride opened 7 years ago

maxiride commented 7 years ago

— no intervention needed

noplanman commented 7 years ago

Vagrant is for the example-bot, right? Not the docs

maxiride commented 7 years ago

Vagrant is for the example-bot, right? Not the docs

Yes and no the Vagrantfile I made after initializing the VM, installs several stuff AND runs a git clone of the example-bot repo PLUS a composer install on the freshly cloned repo.

I'm also planning to modify it more to run a mysql_secure_installation, and create a user called dbuser, with the password dbpass and a databse named dbname just like in the default fields of the example-bot

:point_right: So in this way, once someone runs the vagrant up with this vagrantfile he has a ready to go bot —except for the getUpdatesCLI.php bot name\token which can't be automated and needs a user input.

This overkill plug-n-play solution is meant for having a quickstart for real, where the user can start fiddling with the example commands code, have an overview of it and get an understanding of the framework while manipulating it. I believe there is no better way to learn than reading and applying.

All of this comes from the general idea that the example-bot should be a noob proof as possible. Kinda KISS way of doing it till once can grasp how to do stuff alone.

TL;DR Having said all of this I believe that the Vagrantfile should be shipped with the docs.

noplanman commented 7 years ago

Ok for the top part of your comment.

Absolutely agree with "quickstart for real", as that's the best way to learn.

Regarding the vagrant setup, this for me would be a lot more logical as a user:

  1. Download example-bot.zip
  2. Unzip
  3. vagrant up

It seems weird to have to download the vagrantfile from the docs, but I'm totally open to hear your idea. How do you see the workflow of a user actually getting the vagrantfile and starting the development environment?

maxiride commented 7 years ago

I need to check better when the shared folder is mounted, if before or after the shell provisioning phase. If the mount happens after the shell provisioning we can't run a composer install on a not yet present example-bot. Will check :point_up: :thinking: I just thought of another issue: the actual Vagrantfile contains instructions to git clone the repo and run a composer install on it (and it works fine for now) but this would happen for every time the VM is brought up with the --provision option (which shouldn't happen in a common user case) but in the case that it happens eventual changes made to the example-bot will be lost\overwritten. So maybe it doesn't even matter my first, point since your method is more secure.

The workflow I imagine is that a user lands on the example-bot repo or a future website landing page and it is guided to open the docs, here it is presented with a preliminary preview of the framework capabilities and two paths:

:point_right: The former guides the user to quickly have a functioning example-bot, with general hints about what is happening during the setup of the environment and initial configuration. Once the bot is up and running all the example Commands will be presented, for each one I plan to comment and elaborate what it's happening almost line by line like taking by hand a 5yr old boy.

After such extensive tour of the framework (which can be of course skipped) a custom command creation example is presented. By now enough methods and entities should be known by our hypothetical user.

Then the Webhook configuration is introduced with explanation of the GET POST scheme and a Webhook method is implemented (if we get ngrok up and kicking). --> end

:point_right: The latter (Core) will just inform the (maybe experienced) how to initialize the framework with an example composer.json and that the MySQL database needs to be initialized with structure.sql. No commands or step by step passages are presented, maybe just links back to the Let's Play part for reference.

A list of the entities and methods (types, methods and inlinequery) is presented with a brief recap of the allowed\requested parameters for its $data array

Brief recap of how the channel integration and administraton works.

A note about the logging.

I guess it's everything I wanted to say. Going to sleep now, if something catches up on my mind I'll add it. Let me know what do you think and of course how you would expect the user experience to be.

maxiride commented 7 years ago

Did my stuff and...

I need to check better when the shared folder is mounted, if before or after the shell provisioning phase. If the mount happens after the shell provisioning we can't run a composer install on a not yet present example-bot. Will check

:point_up: The shared folder is mounted before the shell provisioning phase. So we have a go.

Given this :point_down:

:thinking: I just thought of another issue: the actual Vagrantfile contains instructions to git clone the repo and run a composer install on it (and it works fine for now) but this would happen for every time the VM is brought up with the --provision option (which shouldn't happen in a common user case) but in the case that it happens eventual changes made to the example-bot will be lost\overwritten.

I'll change the vagrantfile and the docs to the reflect your usage proposal which I now think it is indeed more valid and fail proof.

noplanman commented 7 years ago

how you would expect the user experience to be

Quite similar to what you've outlined.

As for the beginners part, totally this:

comment and elaborate what it's happening almost line by line

That was on my TODO list too, to add proper descriptions of what each command does in the file header. We'll need to find good wording for the "line by line" commenting, not to bloat it. I've seen examples out there that are so overloaded with comments, that it becomes difficult to actually see the code and how it works. But we'll find a good solution for this, I'm positive.

Back to the workflow...

User sees that there is an example-bot repository that can easily be downloaded and started!

Optional: For the provision, we could even go as far as doing a mini installation help 🎉 

$ What is the name of your bot?
whoop_bot
$ What is the API key of your bot?
123:abc

At this point, the user should know enough about how the bot works to start digging into the code.

As you mentioned, getUpdates with DB is the default for starting out, as it's also the easiest for debugging. (TODO: Have a great page about debugging bot code!)

Then, when user feels comfortable with that, the webhook way can be tested (using ngrok or localtunnel).

As for multiple provisions, that shouldn't be a problem, as the user must learn never to change anything in the vendor folder, and also the example-repo would have been downloaded as a zip file, not a git clone.

Hope my thoughts make sense so far!

maxiride commented 7 years ago

Optional: For the provision, we could even go as far as doing a mini installation help

Found out two ways so far to achieve this:

noplanman commented 7 years ago

I like point 3 (credentials.php) the most, as it's independent of any environment stuff and can also be used stand-alone, without using vagrant at all.