search

Icinga / icingaweb2

A lightweight and extensible web interface to keep an eye on your environment. Analyse problems and act on them.
https://icinga.com/get-started/
GNU General Public License v2.0
812 stars 282 forks source link

Icinga Web Development Guide #4109

Open lippserd opened 4 years ago

lippserd commented 4 years ago

Hi,

Since we're heavily lacking documentation on how Icinga Web works and how to get started with module development, I want to elaborate what's necessary for a useful guide. I think it makes sense that we settle on the index here and create the contents in a new repository, e.g. Icinga/web-development.

The following is an abstract of the main topics the guide should cover. Please add your feedback. What's missing? What is not necessary? What should be explained in detail? ...

Icinga Web Development Guide

Introduction

We should start off with a little explanation on how Icinga web development looks like and which layers are necessary in order to build a web application:

Programming, Markup and Database Languages

The guide should explain our used languages, i.e.

Sever-side

Client-side

Markup

Storage

Browser, OS and Web Server Support

The guide should state which browsers, operating systems and web servers the Icinga web ecosystem supports.

PHP and JavaScript Style Guide

Of course, it is never bad to mention the style guides somewhere.

Basics and Technologies

Before deep diving into writing code, we should explain necessary basics and technologies:

Git

This chapter should cover branch naming conventions and workflows, commit message anatomy and provide a cheat sheet for common Git magic that we use every day, e.g. squash, rebase, interactive rebase, git add -p.

SQL

We follow some conventions when designing databases and learned best practices during our developments which are definitely worth sharing.

Development Environment

We should have a dedicated chapter for setting up a dev environment also integrating XDebug. I do think that this will be a docker setup.

Development

This is an incomplete list of topics which the development chapter should cover, and it also only lists the main topics for the moment:

/cc @nbuchwitz @Mikesch-mp @mcktr @patrickpr @nunofernandes @archandha @cstegm @LordHepipud @friesoft @plsatin @b0e @attachmentgenie @wols @tobias-urdin

attachmentgenie commented 4 years ago

great initiative, seems like a comprehensive list already

nbuchwitz commented 4 years ago

Thanks for taking the initiative! The lists looks already very compressive. Maybe it's worth mentioning which frameworks and libraries already exist in the Icinga ecosystem (IPL, react, JS frameworks etc.)

lippserd commented 4 years ago

Thanks for taking the initiative! The lists looks already very compressive. Maybe it's worth mentioning which frameworks and libraries already exist in the Icinga ecosystem (IPL, react, JS frameworks etc.)

Yeah, absolutely makes sense. Thx. I wanted to add the IPL (Icinga PHP Library) to the list anyway since we'll add docs, guides and blog posts over the next weeks as well.

patrickpr commented 4 years ago

Hi,

Nice idea. For now I don't see anything to add.

For the dev environment, I prefer using virtual machines instead of docker and I can provide description/process/VM  of my environment.

Regards,

Patrick Proy

Le 23/03/2020 à 22:12, Eric Lippmann a écrit :

Hi,

Since we're heavily lacking documentation on how Icinga Web works and how to get started with module development, I want to elaborate what's necessary for a useful guide. I think it makes sense that we settle on the index here and create the contents in a new repository, e.g. Icinga/web-development.

The following is an abstract of the main topics the guide should cover. Please add your feedback. What's missing? What is not necessary? What should be explained in detail? ...

Icinga Web Development Guide

Introduction

We should start off with a little explanation on how Icinga web development looks like and which layers are necessary in order to build a web application:

  • Explain frontend development (client-side)
  • Explain backend development (server-side)

  • Explain storage features (files, database)

    Programming, Markup and Database Languages

The guide should explain our used languages, i.e.

Sever-side

  • PHP 5.6+, preferably PHP7

Client-side

  • JavaScript: ES5 (ES6 once we updated our code base)

Markup

  • HTML5
  • CSS3

Storage

  • INI and JSON files
  • MySQL

  • PostgreSQL

    Browser, OS and Web Server Support

The guide should state which browsers, operating systems and web servers the Icinga web ecosystem supports.

PHP and JavaScript Style Guide

Of course, it is never bad to mention the style guides somewhere.

Basics and Technologies

Before deep diving into writing code, we should explain necessary basics and technologies:

  • HTTP protocol o This may include an explanation for our special HTTP headers and their handling, but there may also be an extra chapter for this
  • Cookies o This may include information about our cookies and their handling, but there may also be an extra chapter for this
  • Ajax
  • MVC
  • JavaScript and CSS delivery
  • X-column layout
  • URL handling
  • Form redirects
  • Flow of requests, i.e. first request is a full-page load including the delivery of JavaScript and CSS and every subsequent request is AJAX
  • Convention over configuration

  • Translation

    Git

This chapter should cover branch naming conventions and workflows, commit message anatomy and provide a cheat sheet for common Git magic that we use every day, e.g. squash, rebase, interactive rebase, git add -p.

SQL

We follow some conventions when designing databases and learned best practices during our developments which are definitely worth sharing.

Development Environment

We should have a dedicated chapter for setting up a dev environment also integrating XDebug. I do think that this will be a docker setup.

Development

This is an incomplete list of topics which the development chapter should cover, and it also only lists the main topics for the moment:

  • Conventions, e.g. naming, directory structure, meta information
  • Controllers
  • Auto-refresh
  • Views
  • Custom CSS
  • Forms
  • Configuration
  • Menu
  • Dashboards
  • Database access
  • Permissions and restrictions
  • Hooks
  • Translation
  • Custom JS
  • CLI

/cc @nbuchwitz https://github.com/nbuchwitz @Mikesch-mp https://github.com/Mikesch-mp @mcktr https://github.com/mcktr @patrickpr https://github.com/patrickpr @nunofernandes https://github.com/nunofernandes @archandha https://github.com/archandha @cstegm https://github.com/cstegm @LordHepipud https://github.com/LordHepipud @friesoft https://github.com/friesoft @plsatin https://github.com/plsatin @b0e https://github.com/b0e @attachmentgenie https://github.com/attachmentgenie @wols https://github.com/wols @tobias-urdin https://github.com/tobias-urdin

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/Icinga/icingaweb2/issues/4109, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAWHIMWSJOBHEHYTBCY4OZDRI7GC7ANCNFSM4LSFU3LQ.

Mikesch-mp commented 4 years ago

This is AWESOME

K0nne commented 4 years ago

That's exactly what some colleagues of me are waiting for 🙏

mcktr commented 4 years ago

Hi,

thanks for opening this issue and also for inviting community members for discussion. I think together with the community we establish a good development documentation.

I think it makes sense that we settle on the index here and create the contents in a new repository, e.g. Icinga/web-development.

Can we reconsider this? I would like to have the development documentation included in this repository, like it is in the repository of the core Icinga 2. I also think we should use the same approach in every project repository. Thereby new contributors know that they will always find the development documentation at a specific place, the repository where the contributor is working on.

I understand that the web repositories may differ from the core and they share a big amount of development documentation which then needs double maintenance. To tackle this problem I suggest that the main development documentation is located here, the modules than only contains documentation for their specialities and for all other they refer to the main web development documentation.

I am not against the first suggestion per se, this is only what is floating around in my head while reading with an eye on new contributors and how they search for documentation. I am open for counter opinions maybe I have one aspect not on my radar.

Best regards Michael

LordHepipud commented 4 years ago

It's not as complex as an Icinga Web 2 module, but for the new Icinga for Windows tool I tried to start with a step-by-step developer guide to give some ideas on how for example a custom background daemon can be written from scratch and some function explanations.

The documentation for that is already online: Icinga for Windows Developer Guide

It is far from finished and more hands-on guides are hopefully following soon, but at least I hope this is a good start for this certain project.

Maybe We can approach Icinga Web 2 modules in a similar way?

nilmerg commented 4 years ago

We should try to avoid explaining topics in too much detail which are already well documented externally. This applies to the following:

Things I'd like to see added:

--

@mcktr The basic documentation such as installation and configuration still will be kept in each repository. Development and end-user documentation however has a way more broad coverage of common topics and needs also updates due to changing technology and, well, additional chapters (over time). That's why a separate versioning system comes in handy, you can easily create different releases (versions) of documentation. Sure, we then have to ensure contributors are aware of this place but that's not a huge problem I guess. :smile:

onkobu commented 3 years ago

I was forwarded here from issue #4296. From my point of view writing documentation is tedious and the result is always stale. I'd appreciate some structured documentation in the code. Maybe generating some formatted (HTML?) output to disk saves some IDE/ symbol backtracking to reconstruct a callstack's types in my head.

The only abstract section above would be some kind of coarse grained architecture. This is only to separate the different components and principles. It also serves as a sort of foundation for decisions: where should I put some auto-refresh or where is it discouraged.