mirror of
https://github.com/letscontrolit/ESPEasy.git
synced 2026-07-28 04:07:47 +00:00
[Docs] Development guide restrucured and extended
This commit is contained in:
Ton Huisman
@@ -173,17 +173,26 @@ For Linux, you may need to install 99-platformio-udev.rules to make PlatformIO u
|
||||
Starter guide for setting up local development of ESPEasy
|
||||
=========================================================
|
||||
|
||||
For those with less development experience, or less experience in using Github, this chapter is intended as a ``How To`` guide to get started with development on ESPEasy.
|
||||
For those with less development experience, or less experience in using Github, this chapter is intended as a **How To** guide to get started with development on ESPEasy.
|
||||
|
||||
Github account
|
||||
--------------
|
||||
|
||||
First requirement is to have a Github account. You can either use an existing account or create one (it's free), by opening a browser on https://github.com, and following the steps after clicking the Sign up (for Github) button.
|
||||
|
||||
The Github flow
|
||||
---------------
|
||||
|
||||
When you want to extend some function of the software at hand, ESPEasy in this case, there is a general flow, or 'how things are done here', that is common for Github, but most likely somewhat different from other software development flows or processes.
|
||||
|
||||
The usual Github flow or way of working is described nicely on this page: `Understanding the GitHub flow <https://guides.github.com/introduction/flow/>`_ If you have not used git or github before, or have little knowledge on how all this works, this explanation can be very helpful.
|
||||
|
||||
Fork the ESPEasy repository
|
||||
---------------------------
|
||||
|
||||
As an 'external' developer, no (direct) write-access is granted to the ESPEasy repository. To still be able to do development work, a 'fork' (git terminology for a copy) has to be made to your own account. So, log into your Github account from a webbrowser, browse to https://github.com/letscontrolit/ESPEasy and click the Fork button to create that copy:
|
||||
`Reasons for forking <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_ Quote: "A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project."
|
||||
|
||||
As an 'external' developer, no (direct) write-access is granted to the ESPEasy repository. To experiment with the code, and still be able to later have your development work included in the project, a 'fork' has to be made to your own account. So, log into your Github account from a webbrowser, browse to https://github.com/letscontrolit/ESPEasy and click the Fork button to create that copy:
|
||||
|
||||
.. image:: Github_fork_button.png
|
||||
:alt: Github fork button
|
||||
@@ -195,14 +204,16 @@ After this completes, you can view the fork in your Github dashboard at https://
|
||||
Install VSCode and PlatformIO
|
||||
------------------------------
|
||||
|
||||
Earlier on this page, a complete description has been given on how to install **PlatformIO with VSCode** with the required and advised optional extensions and git command-line tools.
|
||||
Earlier on this page, a complete description has been given on how to install **PlatformIO with VSCode** with the required and advised optional extensions and the git command-line tools.
|
||||
|
||||
NB: PlatformIO is often shortened to PIO.
|
||||
|
||||
Clone your forked repository to your computer
|
||||
---------------------------------------------
|
||||
|
||||
To get the ESPEasy sources on your computer for compilation and making modifications, a 'clone' (git terminology) has to be made, using the ``git clone`` command
|
||||
`Cloning a repository <https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository>`_ Quote: "You can clone your repository to create a local copy on your computer and sync between the two locations."
|
||||
|
||||
To get the ESPEasy sources on your computer for compilation and making modifications, a 'clone' has to be made, using the ``git clone`` command
|
||||
|
||||
Open a Command prompt (Windows) or Terminal session (MacOS or Linux), and ``cd`` to a folder where the ESPEasy project can/should be a subfolder of.
|
||||
|
||||
@@ -224,25 +235,25 @@ Completed:
|
||||
.. image:: Github_clone_completed.png
|
||||
:alt: Github clone completed
|
||||
|
||||
To be able to bring your changes as a 'pull request' (git terminology, often referred to as a 'PR') to the ESPEasy repository, a connection has to be made from your local clone to the 'upstream' (git terminology) repository, being the original ESPEasy repo. This command needs to be issued **only once** after cloning the repository into a folder on your computer, and should be executed from the ``ESPEasy`` folder that was just created:
|
||||
To be able to get the latest changes from the original project into your local copy, and to bring your changes as a 'pull request' (git terminology, often referred to as a 'PR', further explained below) to the ESPEasy repository, a connection has to be made from your local clone to the 'upstream' (git terminology) repository. This command needs to be issued **only once** after cloning the repository into a folder on your computer, and should be executed from the ``ESPEasy`` folder that was just created:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
git remote add upstream https://github.com/letscontrolit/ESPEasy
|
||||
|
||||
Now this Command prompt / termninal can be closed.
|
||||
Now this Command prompt / terminal can be closed.
|
||||
|
||||
Open the folder with ESPEasy project
|
||||
------------------------------------
|
||||
|
||||
Start VSCode, and open the ESPEasy folder that was just created. First thing, VSCode will ask you if you trust the authors of the files. The easiest option is to respond by clicking the ' Yes, I trust the authors' button, as that is the only way to get unrestricted access to the sources. After that confirmation, VSCode will take a little time to initialize all plugins.
|
||||
Start VSCode, and open the ESPEasy folder that was just created. In Windows you can right-click the ESPEasy folder and select the 'Open with Code' option. First thing when opening a git repository, VSCode will ask you if you trust the authors of the files. The easiest option is to respond by clicking the 'Yes, I trust the authors' button, as that is the only way to get unrestricted access to the sources. After that confirmation, VSCode will take a little time to initialize all plugins.
|
||||
|
||||
Depending on your usual workflow, the current VSCode environment can be saved as a 'Workspace' (VSCode terminology), so it can be easily re-opened. This is especially useful if you also use VSCode for other projects/editing work.
|
||||
|
||||
Compile an ESPEasy PIO environment
|
||||
----------------------------------
|
||||
|
||||
ESPEasy supports several differnt configurations of ESP units, ESP8266, ESP8285 and ESP32, and also different predefined hardware configurations and sets of plugins & controllers. This has been turned into several different PlatformIO environments, to make managing the different builds as easy as possible.
|
||||
ESPEasy supports several different configurations of ESP units, ESP8266, ESP8285 and ESP32, and also some predefined hardware configurations and sets of plugins & controllers. This has been turned into several different PlatformIO environments, to make managing the different builds as easy as possible.
|
||||
|
||||
To compile such 'environment' (PIO terminology), select the PIO button (it looks like an alien) in VSCode:
|
||||
|
||||
@@ -263,17 +274,142 @@ The first build will take some extra time, as PIO needs to first install some of
|
||||
|
||||
(NB: For this build all tools and libraries where already installed, and the computer isn't that slow, so total execution didn't take too much time.)
|
||||
|
||||
Create a new branch
|
||||
-------------------
|
||||
|
||||
As shown above, the git workflow starts by creating a new branch to do the development work in. This will record all changes to the sourcecode you make, and can be put in as a pull request for ESPEasy.
|
||||
|
||||
A new branch is created either by clicking on the 'mega' branch name and selecting the option 'Create new branch...' from the list presented. Then a new braanch name should be typed. Naming does have some conventions. New features are often named like 'feature/purpose-of-the-feature', and bugfixes are usually named like 'bugfix/what-is-to-be-fixed'. For the addition of this documentation, I've created a branch named 'feature/how-to-guide-for-new-developers':
|
||||
|
||||
.. image:: VSCode_create_branch.png
|
||||
:alt: VSCode create branch
|
||||
|
||||
.. image:: VSCode_type_branch_name.png
|
||||
:alt: VSCode type the branch name
|
||||
|
||||
.. image:: VSCode_statusbar_new_branch.png
|
||||
:alt: VSCode statusbar with new branch name
|
||||
|
||||
As an alternative, a new branch can also be created using command-line commands, you can type these after opening a Terminal in VSCode:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
git checkout -b feature/how-to-guide-for-new-developers
|
||||
|
||||
The nett result of this command is the same as from using the UI flow shown above.
|
||||
|
||||
Change code of ESPEasy
|
||||
----------------------
|
||||
|
||||
To improve or extend an existing plugin or other code of ESPEasy, after creating a new branch for it, open the source file and modify code the as needed. Then compile and see if it all is according to the requirements of the compiler.
|
||||
|
||||
Testing is done by uploading the result to an ESPEasy unit, testing the changed functionality to ensure no errors or undesired behavior remain in the code.
|
||||
|
||||
This uploading can be done in 2 ways:
|
||||
|
||||
* *Use the Upload feature of PIO*: If the ESP unit is connected to the computer via USB and the serial chip of the unit is recognized by the OS, the Upload option can be selected to compile the sources (only what was changed since the last compilation) and start the upload procedure. After uploading the ESP will restart
|
||||
* *Use the Update Firmware option of ESPEasy*: On the Tools tab of ESPEasy, there is a button Update Firmware available (on units that have enough free Flash space) so a new .bin file can be uploaded. The latest successful compiled file can be found in the ``build_output/bin`` subfolder of your ``ESPEasy`` folder.
|
||||
|
||||
Writing documentation
|
||||
---------------------
|
||||
|
||||
Updating, or adding if it does not yet exist, the documentation is a useful activity that should be part of changing or adding to the ESPEasy code. Some of the optional VSCode extensions are specifically aimed at that task.
|
||||
|
||||
The documentation is created in the reStructuredText format, using mostly a ``.rst`` extension, and can be built locally by installing the sphinx tool. This can be installed manually by opening a Terminal window in VSCode (an already open Terminal can also be used) and issuing these commands:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
cd docs
|
||||
pip install -r requirements.txt
|
||||
|
||||
The python tool ``pip`` will read the file ``requirements.txt`` and install all tools mentioned in the file. Depending on what is already installed, more or less of the modules will be installed. This should be a 1-time process, though sometimes updates to the tooling are made, and re-running these commands will then update all to the latest, possibly required, version.
|
||||
|
||||
The sources for the documentation are in the repository in the ``docs`` folder and its subfolders.
|
||||
|
||||
When adding screenshots it is advised to use the ``.png`` file format, as that usually has the best visible result for screenshots. When adding photos, the ``.jpg`` file format will do nicely.
|
||||
|
||||
Documentation for writing in reStructuredtext format can be found on the `Sphinx website <https://www.sphinx-doc.org/en/master/>`_
|
||||
|
||||
Building the documentation into html files, for reviewing locally, can be done by running this command from the ``docs`` folder:
|
||||
|
||||
On Windows:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
.\make.bat html
|
||||
|
||||
On Linux or MacOS:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
make html
|
||||
|
||||
The resulting output can be found in this folder with the ESPEasy folder: ``docs/build/html`` and can be viewed by opening the file ``index.html`` in a browser. Then the normal navigation within the documentation is available.
|
||||
|
||||
TODO: Add documentation about the structure of the documentation.
|
||||
|
||||
Add a plugin to ESPEasy
|
||||
-----------------------
|
||||
|
||||
Instead of just changing an existing plugin or some other feature of ESPEasy, also, new plugins can be added. Plugins can be taken from the ESPEasyPlayground repository at https://github.com/letscontrolit/ESPEasyPluginPlayground, or from other sources.
|
||||
|
||||
It requires sufficient testing, and analysis of the runtime behavior, of that piece of code, before it should be submitted for a pull request.
|
||||
|
||||
Especially for new plugins, it is highly recommended to write documentation, as explained in the previous paragraph.
|
||||
|
||||
Commit and create a pull request
|
||||
--------------------------------
|
||||
|
||||
After changing and testing sourcecode, using builds uploaded to an actual ESP unit, the time has come to present the changed code to ESPEasy to be included in the regular build. This is called a 'pull request', and is explained in this Github documentation `About pull requests <https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_ Quote: "Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub."
|
||||
|
||||
To make changes available for others they have to be 'staged' and 'committed' (git terminology) before it can be uploaded (pushed) to the repository. This stage and commit is a 2 step process, and easiest done from the VSCode UI. First select the GitLens plugin, and select the files that need to be staged and committed:
|
||||
|
||||
.. image:: VSCode_stage_changes.png
|
||||
:alt: VSCode stage changed files
|
||||
|
||||
Selecting multiple files and clicking one of the ``+`` buttons next to the selected files, will put the files in the staging area, so they can be committed. Every commit will need a useful commit message, that describes what the commit is all about:
|
||||
|
||||
.. image:: VSCode_staged_files.png
|
||||
:alt: VSCode list of staged files and commit message
|
||||
|
||||
Clicking the marked check button, or using the Ctrl-Enter key combination, will commit the staged files, using the commit message just typed.
|
||||
|
||||
After the commit is completed, more commits can be added, if desired. It is good practice to commit separate functional changes in separate commits. That will make the review process, as explained in the Github flow documentation, easier.
|
||||
|
||||
To have the commit(s) to be presented as a pull request they must be published, and the easiest way to accomplish that is to use the Publish Changes button in VSCode:
|
||||
|
||||
.. image:: VSCode_Publish_changes.png
|
||||
:alt: VSCode publish change button
|
||||
|
||||
After clicking that button, you have to select the source the changes should be published to. As we don't have (direct) write access to the upstream ESPEasy repository, we can only publish to the 'origin' (git terminology), our own fork of the repository, so that option should be selected by clicking it, or pressing the Enter key:
|
||||
|
||||
.. image:: VSCode_select_publish_source.png
|
||||
:alt: VSCode select publish source
|
||||
|
||||
If this is the first time you try to push any changes to your repository, VSCode, or actually the GitLens plugin, will ask for your Github credentials, and will switch back and forth a few times between your webbrowser and VSCode to complete the authentication process. This is as intended.
|
||||
|
||||
Now that the Publish Changes is done, the pull request can be created. We have to switch to the ESPEasy repository on Github to complete that task. The Github website will show the options for that, assuming you are still logged in to your Github account from that browser:
|
||||
|
||||
When opening the https://github.com/letscontrolit/ESPEasy page (or refreshing it if it was already open), a message is shown that you have committed something to your forked repository, that can be pull-requested into the ESPEasy repository:
|
||||
|
||||
.. image:: Github_start_new_pull_request.png
|
||||
:alt: Github start new pull rquest
|
||||
|
||||
After clicking the 'Compare and pull request' button, a description for the PR can be given, the title can be updated, and the pull request created. Helpful information can be found in `Creating a pull request from a fork <https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_
|
||||
|
||||
If needed, or requested during the review process, more changes can be made to files, or files added or deleted, then staged and committed, after which these can be pushed to Github, and the changes will be automatically added to the PR.
|
||||
|
||||
Regular maintenance of your fork
|
||||
--------------------------------
|
||||
|
||||
If you have forked ESPEasy before (or some time ago), and want to start (new) work on a plugin, it is required to update your fork with the latest state of affairs of ESPEasy, to avoid surprises after submitting a PR.
|
||||
If you have forked ESPEasy before (or some time ago), and want to start (new) work on the code, it is required to update your fork with the latest state of affairs of ESPEasy, to avoid surprises after submitting a PR.
|
||||
|
||||
This expects the currently selected 'branch' (git terminology) to be ``mega``, as is visible in the VSCode statusbar:
|
||||
This expects the currently selected 'branch' to be ``mega``, as is visible in the VSCode statusbar:
|
||||
|
||||
.. image:: VSCode_statusbar_mega.png
|
||||
:alt: VSCode statusbar current branch mega
|
||||
|
||||
The desired branch can be selected by clicking the currently selecte branch name as shown in the status bar, or by typing this command from a VSCode terminal window:
|
||||
The desired branch can be selected by clicking the currently selected branch name as shown in the VSCode status bar, or by typing this command from a VSCode terminal window:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@@ -299,90 +435,3 @@ If this is the first time you try to push any changes to your repository, VSCode
|
||||
|
||||
Updating your fork this way should be done at least every time you start new work, and can be done more often if desired. If kept up to date you will avoid starting with an out-dated state of the repository.
|
||||
|
||||
Create a new branch
|
||||
-------------------
|
||||
|
||||
An often used git workflow starts by creating a new branch to do the development work in. This will record all changes to the sourcecode you make, and can be put in as a pull request for ESPEasy.
|
||||
|
||||
A new branch is created either by clicking on the 'mega' branch name and selecting the option Create new branch... from the list presented. Then a new braanch name should be typed. Naming does have some conventions. New features should get named like 'feature/purpose-of-the-feature', and bugfixes are usually named like 'bugfix/what-is-to-be-fixed'. For the addition of this documentation, I've created a branch named 'feature/how-to-guide-for-new-developers':
|
||||
|
||||
.. image:: VSCode_create_branch.png
|
||||
:alt: VSCode create branch
|
||||
|
||||
.. image:: VSCode_type_branch_name.png
|
||||
:alt: VSCode type the branch name
|
||||
|
||||
.. image:: VSCode_statusbar_new_branch.png
|
||||
:alt: VSCode statusbar with new branch name
|
||||
|
||||
As an alternative, a new branch can also be created using command-line commands:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
git branch feature/how-to-guide-for-new-developers
|
||||
git checkout feature/how-to-guide-for-new-developers
|
||||
|
||||
The nett result of these commands is the same as from using the UI flow shown above.
|
||||
|
||||
Change an existing plugin
|
||||
-------------------------
|
||||
|
||||
To improve or extend an existing plugin, after creating a new branch for it, just open the plugin source from the src folder, or its accompanying code in the ``src/src/PluginStructs`` folder, and modify code the as needed. Then compile and see if it all is according to the requirements of the compiler.
|
||||
|
||||
Testing is done by uploading the result to an ESPEasy unit and enabling the plugin, testing the changed functionality to ensure no errors or undesired behavior remain in the code.
|
||||
|
||||
This uploading can be done in 2 ways:
|
||||
|
||||
* *Use the Upload feature of PIO*: If the ESP unit is connected to the computer via USB and the serial chip of the unit is recognized by the OS, the Upload option can be selected to compile the sources (only what was changed since the last compilation) and start the upload procedure. After uploading the ESP will restart
|
||||
* *Use the Update Firmware option of ESPEasy*: On the Tools tab of ESPEasy, there is a button Update Firmware available (on units that have enough free Flash space) so a new .bin file can be uploaded. The latest successful compiled file can be found in the ``build_output/bin`` subfolder of your ``ESPEasy`` folder.
|
||||
|
||||
Updating, or adding if it does not yet exist, the documentation is a useful activity that should be part of changing or adding to the ESPEasy code. Some of the optional VSCode extensions are specifically aimed at that task.
|
||||
|
||||
The sources for the documentation are in the repository in the ``docs`` folder and its subfolders.
|
||||
|
||||
Add a plugin to ESPEasy
|
||||
-----------------------
|
||||
|
||||
Instead of just changing an existing plugin or some other feature of ESPEasy, also, new plugins can be added. Plugins can be taken from the ESPEasyPlayground repository at https://github.com/letscontrolit/ESPEasyPluginPlayground, or from other sources.
|
||||
|
||||
It requires sufficient testing, and analysis of the runtime behavior, of that piece of code, before it shopuld be submitted for a pull request.
|
||||
|
||||
Commit and create a pull request
|
||||
--------------------------------
|
||||
|
||||
After changing and testing sourcecode, the time has come to submite the code to ESPEasy to be included in the regular build.
|
||||
|
||||
The way to make changes available for others they have to be 'staged' and 'committed' (git terminology) before it can be pushed to the repository. This stage and commit is a 2 step process, best be done from the VSCode UI. First select the GitLens plugin, and select the files that need to be staged and committed:
|
||||
|
||||
.. image:: VSCode_stage_changes.png
|
||||
:alt: VSCode stage changed files
|
||||
|
||||
Clicking one of the + buttons form the selected files, will put the files in the staging area, so they can be committed. Every commit will need a useful commit message, that describes what the commit is all about:
|
||||
|
||||
.. image:: VSCode_staged_files.png
|
||||
:alt: VSCode list of staged files
|
||||
|
||||
Clicking the marked check button will commit the staged files, using the commit message just typed. As an alternative, Ctrl-Enter can also be used to complete the commit.
|
||||
|
||||
After the commit is completed, more commits can be added, if desired.
|
||||
|
||||
To prepare the commit(s) to be presented as a pull request, the easiest way to accomplish that is to use the Publish Changes button:
|
||||
|
||||
.. image:: VSCode_Publish_changes.png
|
||||
:alt: VSCode publish change button
|
||||
|
||||
After clicking that button, you have to select the source the changes should be published to. As we don't have (direct) write access to the upstream ESPEasy repository, we can only publish to the 'origin' (git terminology), our own fork of the repository, so that option should be selected by clicking it, or pressing the Enter key:
|
||||
|
||||
.. image:: VSCode_select_publish_source.png
|
||||
:alt: VSCode select publish source
|
||||
|
||||
Now that the Publish Changes is done, the pull request can be created. We have to switch to the ESPEasy repository to complete that task. The Github website will show the options for that, assuming you are still logged in to your Github account from that browser:
|
||||
|
||||
When opening the https://github.com/letscontrolit/ESPEasy page, a message is shown that you have commited something to your forked repository, that can be pull-requested into the ESPEasy repository:
|
||||
|
||||
.. image:: Github_start_new_pull_request.png
|
||||
:alt: Github start new pull rquest
|
||||
|
||||
After clicking the 'Compare and pull request' button, a descrption for the PR can be given, and the pull request created.
|
||||
|
||||
Now, more changes can be made to files, then staged and committed, after which these can be pushed to Github, and the changes will be automatically added to the PR.
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 9.8 KiB After Width: | Height: | Size: 11 KiB |
Reference in New Issue
Block a user