diff --git a/doc/Developing/Getting-Started.md b/doc/Developing/Getting-Started.md new file mode 100644 index 0000000000..d9da29bf74 --- /dev/null +++ b/doc/Developing/Getting-Started.md @@ -0,0 +1,65 @@ +# Get ready to contribute to LibreNMS + +This document is intended to help you get your local environment set up to contribute code to the LibreNMS project. + +## Setting up a development environment + +When starting to develop, it may be tempting to just make changes on your production server, but that will make things harder +for you. Taking a little time to set up somewhere to work on code changes can really help. + +Possible options: + * A Linux computer, VM, or container + * Another directory on your LibreNMS server + * Windows Subsystem for Linux + +### Set up your development git clone + 1. Follow the [documentation on using git](Using-Git.md) + 2. Install development dependencies `./composer_wrapper.php install` + 3. Set variables in .env, including database settings. Which could be a local or remote MySQL server including your production DB. + ```dotenv +APP_ENV=local +APP_DEBUG=true +... + +``` + 4. Start a development webserver `./lnms serve` + 5. Access the Web UI at http://localhost:8000 + +### Automated testing +LibreNMS uses continuous integration to test code changes to help reduce bugs. This also helps guarantee the changes you +contribute won't be broken in the future. +You can find out more in our [Validating Code Documentation](Validating-Code.md) + +### Polling debug output +You can see detailed info by running your polling code in debug mode. If you are looking at a specific +```bash +./discovery.php -d -h HOSTNAME +./poller.php -d -h HOSTNAME +``` + +### Inspecting variables +Sometimes you want to find out what a variable contains (such as the data return from an snmpwalk). +You can dump one or more variables and halt execution with the dd() function. +```php +dd($variable1, $variable2); +``` + +### Inspecting web pages +Installing the development dependencies and setting APP_DEBUG enables the [Laravel Debugbar](https://github.com/barryvdh/laravel-debugbar) +This will allow you to inspect page generation and errors right in your web browser. + +### Better code completion in IDEs and editors +You can generate some files to improve code completion. +(These file are not updated automatically, so you may need to re-run these command periodically) + +```bash +./lnms ide-helper:generate +./lnms ide-helper:models -N +``` + +### Emulating devices +You can capture and emulate devices using [Snmpsim](https://github.com/etingof/snmpsim). LibreNMS has a set of scripts to make it easier to work with snmprec files. +[LibreNMS Snmpsim helpers](https://github.com/librenms/librenms-snmpsim) + +### Laravel documentation +You can find a lot of how LibreNMS works by following the [Laravel Documentation](https://laravel.com/docs/) diff --git a/doc/Developing/index.md b/doc/Developing/index.md index c94f600620..3fdc4b3879 100644 --- a/doc/Developing/index.md +++ b/doc/Developing/index.md @@ -4,7 +4,7 @@ path: blob/master/doc/ # Copyright and Licensing All contributors to LibreNMS retain copyright to their own code and are not required to sign over their rights to any other party. Code should be licensed -under the GPLv3 and MUST not contain non-GPL Observium code or GPL incompatible code. +under the GPLv3 and MUST NOT contain non-GPL Observium code or GPL incompatible code. To be safe do not view Observium code at all. See [Licensing](Licensing.md) for more details. # General Guidelines @@ -20,15 +20,15 @@ To be safe do not view Observium code at all. See [Licensing](Licensing.md) for code at the same time. This makes it harder to see what's changed. If you need to reformat it after making the change, do so in a separate commit. -- Please join us in [discord](https://t.libren.ms/discord) if you're - able. Collaborating in real time makes the coordination of contributions - easier. +- Please join us in [discord](https://discord.gg/librenms) if you are able. + Collaborating in real time makes the coordination of contributions easier. - Ensure you read the [Code Guidelines](Code-Guidelines.md) documentation and understand the code style that should be adhered to. You can [validate that your code adheres to these guidelines](Validating-Code.md) before submitting. - Check [Style Guidelines](Style-Guidelines.md) for Web UI guidelines and conventions. # How to Contribute? + - [Getting Started](Getting-Started.md) Set up your development environment to make things easier. - [Using Git](Using-Git.md) gives you step-by-step instructions on using git to submit a pull request. - [Code Structure](Code-Structure.md) can help you understand where specific code exists in LibreNMS. - [Creating Documentation](Creating-Documentation.md) It is very important for the continued @@ -46,3 +46,4 @@ be delayed or brief, please be patient or ask for clarification if needed. Thank - [The PHP Practitioner](https://laracasts.com/series/php-for-beginners) - [Object-Oriented Bootcamp](https://laracasts.com/series/object-oriented-bootcamp-in-php) - [Simple Rules for Simpler Code](https://laracasts.com/series/simple-rules-for-simpler-code) + - [Laravel Documentation](https://laravel.com/docs/)