Update README and version files

README.md

@@ -14,98 +14,84 @@ Remote server must use GNU/Linux.
 
 # Installation
 
-## Add dependency 
+## Add dependency
 
 You can install this package via composer using:
 
 ```shell
-composer require --dev hexide-digital/gitlab-deploy
+composer require --dev hexide-digital/gitlab-deploy:^1.3 -W
 ```
 
-And if you are using composer version 2.4 and above, run the [`bump`](https://php.watch/articles/composer-bump) command
+> We specify the option `-W` for composer to downgrade `psr/http-message` package from v2 to v1
+> for the latest Laravel projects
+> (see more in this [issue](https://github.com/GrahamCampbell/Laravel-GitLab/issues/44))
 
-or manually add line to `composer.json`
-
-```json
-{
-    "require-dev": {
-        "hexide-digital/gitlab-deploy": "^1.0"
-    }
-}
-```
-
-then run:
+And if you are using composer version 2.4 and above,
+we recommend run the [`bump`](https://php.watch/articles/composer-bump) command
 
 ```shell
-composer install
+composer bump "hexide-digital/gitlab-deploy"
 ```
 
-## Publish files and examples
+After installation, this package will automatically register its service provider.
 
-The package will automatically register its service provider.
+# Usage
 
-Examples of files to be copied can be viewed in
-[this folder](https://github.com/hexidedigital/laravel-gitlab-deploy/tree/master/examples).
+## Install and publish files
 
-After installing, you maybe want to publish files for deployment and sample files, right? Just do this:
+To publish files for deployment and sample files run command bellow:
 
 ```shell
 php artisan deploy:install
 ```
 
-# Usage
+Examples of files to be copied are
+located in [this folder](https://github.com/hexidedigital/laravel-gitlab-deploy/tree/master/examples).
 
-## Prepare
+## Configurations and prepare access
 
-Open _(after publishing)_ or create the file
-[`deploy/deploy-prepare.yml`](https://github.com/hexidedigital/laravel-gitlab-deploy/blob/master/examples/deploy-prepare.example.yml)
+Open [`.deploy/deploy-prepare.yml`](https://github.com/hexidedigital/laravel-gitlab-deploy/blob/master/examples/deploy-prepare.example.yml)
 and fill all needed options.
 
 For most cases only need to be specified next options:
 
 - **access token** for project repository ([see tip](#gitlab-api-access-token))
-- project **full name** or project **id** ([see tip](#project-full-name-or-id))
-- access for the **server**
-- access for the **database**
+- project **id** ([see tip](#project-id))
+- access to the **server**
+- access to the **database**
 
 But for every stage are available next options:
 
 - repository url
 - executor paths for `php` and `composer`
 - access for the server
-- access for the database
-- access for the mail host (but can be missed)
+- access to the database
+- access to the mail host (but can be omitted)
 
 ## Running configuration command
 
 ### Basic launch
 
-You can begin configuring your project deployment for specific stage (i.e. for `dev` branch) by running:
+You can begin configuring your project deployment for specific **stage name** (i.e. for `dev` branch) by running:
 
 ```shell
 php artisan deploy:gitlab dev
 ```
 
-Important - see what todo [After command executing](#after-command-executing)
-
-> By default, stage are same git branch.
+> Normally, the stage name must be the same as git branch name.
 
-#### Only-print option
+#### After command executing
 
-If you want manually execute commands or just prepare to future deployment, set a `--only-print` option when calling
-command. All command examples will be written to `deploy/dep-log.log` file. All that remains is to copy and execute
-commands from the file.
-
-#### Aliases
+If all tasks completely executed, to enable auto-deployment go to
+`Settings` -> `CI/CD` -> `Variables` and change value for `CI_ENABLED` to `1`.
+After that, when you edit branch with configured deployment, Gitlab will run CI/CD Pipelines automatically.
 
-For more convenient use of the Laravel **artisan** command, you can add command line aliases to `~/.bashrc`
-(or `~/.bash_aliases`). So you can append to file or print a log file with a `--aliases` option when calling command.
+### Only-print launch
 
-## After command executing
-
-If all tasks completely executed, to enable auto-deployment go to
-`Settings` -> `CI/CD` -> `Variables` and change value for `CI_ENABLED` to `1`. After that, when you edit
-branch with configured deployment, Gitlab will run CI/CD Pipelines automatically
+If you want to manually execute commands or just prepare to future deployment,
+set a `--only-print` option when calling command.
+All commands and examples will be written to log files located in `.deploy/logs` folder.
+All that remains is to copy and execute commands from the file.
 
 # Tips for Gitlab
 
@@ -114,31 +100,51 @@ branch with configured deployment, Gitlab will run CI/CD Pipelines automatically
 In order for variables and other deployment options to be created, you need to grant access to the repository settings.
 This package uses the **Gitlab API** method using **Access Tokens**.
 
-To get Access Token follow this path `Settings` -> `Access Tokens`.
+We recommend creating one personal access token and use for future deployment configurations.
+For this navigate to `Profile` -> `Access Tokens` and press `Add new token`.
 
-Fill next options like bellow:
+![profile-add-new-token.png](media/add-new-token.png)
 
-- **Token name** - i.e. `deploy_dev` or `deploy_prod`
-- **Expiration date** - recommended to set 1-2 days (this will be enough)
-- **Role** - `mainterner` - for ability to change repository settings
-- **Scopes** - only `api`
+Then fill the next options:
+
+- **Token name** - name for you to identify token, i.e. `token_for_deployments`
+- **Expiration date** - by default, automatically specified 1 month, but set longer time or remove this date
+- **Scopes** - this package needs only `api` scope, but you can add more scopes
+
+Then click `Create personal access token`.
+
+![creating-personal-access-token.png](media/creating-personal-access-token.png)
+
+After creating, copy this token and save in somewhere safe place, because you won't be able to access it again,
+and set in deploy config file
+
+![created-personal-access-token.png](media/created-personal-access-token.png)
 
-Then click `Create project access token` to see the token. **Make sure you save it - you won't be able to access it
-again.**
+---- 
 
-## Project full name or ID
+If you don't want to use and create personal token, you can create project token with access only for repository.
 
-### Project full name
+To get Access Token follow this path `Settings` -> `Access Tokens` and press `Add new token`.
+
+![project-add-new-token.png](media/add-new-token.png)
+
+Fill next options like bellow:
+
+- **Token name** - any name, `deploy_dev`, `deploy_prod` etc. 
+- **Expiration date** - recommended to set 1-2 days (this will be enough)
+- **Role** - select `mainterner` - this is necessary for the ability to change repository settings
+- **Scopes** - select only `api`, for this package will be enough
 
-You can get full name in different ways, but most simple is copy from browser url.
+Then click `Create project access token` to see the token, copy it and set in deploy config file.
 
-I.e. url looks like `https://gitlab.com/namespace/project_name`, so **full name** will be `namespace/project_name`
+## Project ID
 
-### Project ID
+Open the main page of the repository and on top you can see repository info and project id.
+It also can be copied with button on the right side.
 
-Project ID are placed under this path `Settings` -> `General` -> `Naming, topics, avatar (alredy open)`.
+![project-id.png](media/project-id.png)
 
-But for using project ID you must wrap number to quotes like `"XXXXXXXXXX"` to mark value as string.
+> For using project ID, you must wrap number in file to quotes like `"XXXXXXXXXX"` to mark value as string.
 
 # Can I hire you guys?
 

examples/deploy-prepare.example.yml

@@ -1,7 +1,7 @@
 # schema https://raw.githubusercontent.com/hexidedigital/laravel-gitlab-deploy/develop/schema/deploy-prepare-v1.json
 
 # How to work with the file, read here
-# https://github.com/hexidedigital/laravel-gitlab-deploy#prepare
+# https://github.com/hexidedigital/laravel-gitlab-deploy#configurations-and-prepare-access
 
 version: 1
 
@@ -11,9 +11,8 @@ git-lab:
     # Read where to get this token - https://github.com/hexidedigital/laravel-gitlab-deploy#gitlab-api-access-token
     token: "XXXXXXXXXX"
 
-    # Read about the possible options https://github.com/hexidedigital/laravel-gitlab-deploy#project-full-name-or-id
-    project-id: "NAMESPACE/PROJECT_NAME"
-    # project-id: "000000"
+    # Read where to get this id - https://github.com/hexidedigital/laravel-gitlab-deploy#project-id
+    project-id: "000000"
 
     domain: https://gitlab.hexide-digital.com
 

examples/deploy.php.stub

@@ -3,7 +3,7 @@
 /**
  * Keep this version number to manage file versions in projects
  *
- * @version 1.2
+ * @version 1.3
  */
 
 namespace Deployer;