diff --git a/doc/Pacemaker_Development/en-US/Ch-Evolution.txt b/doc/Pacemaker_Development/en-US/Ch-Evolution.txt index 4c1e657729..d597ed9144 100644 --- a/doc/Pacemaker_Development/en-US/Ch-Evolution.txt +++ b/doc/Pacemaker_Development/en-US/Ch-Evolution.txt @@ -1,104 +1,105 @@ :compat-mode: legacy = Evolution of the project = anchor:ch-evolution[Chapter 5. Evolution] +[id="evolution-foreword"] == Foreword == This chapter is currently not meant as a definite summary of how Pacemaker got into where it stands now, but rather to provide few valuable pointers an entusiasts (presumably software archeologist type of person) may find useful. Moreover, well-intentioned contributors to Pacemaker project may want to review them occasionally since, as the famous quote has it, "those who do not learn history are doomed to repeat it". For anything more talkative with less emphasis on actual code, other places will serve better for the time being (and if not, should not be too hard to volunteer extensions to those writeups): * https://wiki.clusterlabs.org/wiki/Pacemaker[main entry at ClusterLabs community wiki] * https://en.wikipedia.org/wiki/Pacemaker_(software)[entry at wikipedia.org] * https://www.alteeve.com/w/AN!Cluster_Tutorial_2#What_about_Pacemaker.3F[ brief section dedicated to Pacemaker in Digimer's tutorial regarding setting up the cluster with the old Red Hat Cluster Suite like stack] == Common ancestor: 'heartbeat' project == Pacemaker can be considered as a spin-off from `heartbeat', original comprehensive HA suite started by Alan Robertson, and some portions of code are shared, at least on the conceptual level if not verbatim, till today, even if the effective percentage continually declines. Note that till Pacemaker 2.0, it also used to stand for one (and initially the only) of supported messaging back-ends (removal of this support made for one such notable drop of reused code), see also https://github.com/ClusterLabs/pacemaker/commit/55ab749bf0f0143bd1cd050c1bbe302aecb3898e[ pre-2.0 commit 55ab749bf]. The codebase for heartbeat used to be hosted at http://hg.linux-ha.org, but since that does not appear reliably available recently, an archive checkout from 2016 is shared at https://gitlab.com/poki/archived-heartbeat[ as a dedicated read-only repository], and anchored there, the most notable commits are: * https://gitlab.com/poki/archived-heartbeat/commit/bb48551be418291c46980511aa31c7c2df3a85e4[ initial check-in of what turned up to be the basis for Pacemaker later on] * https://gitlab.com/poki/archived-heartbeat/commit/74573ac6182785820d765ec76c5d70086381931a[ drop of now-detached Pacemaker code] Regarding the Pacemaker's split from heartbeat, it evolved stepwise (as opposed to one-off cut), and the last step of full dependency is depicted in https://www.kernel.org/doc/ols/2008/ols2008v1-pages-85-100.pdf#page=14[ The Corosync Cluster Engine] paper, fig. 10. This article also provides a good reference regarding wider historical context of the tangentially (and deeper in some cases) meeting components around that time. === Influence of 'heartbeat' on Pacemaker === On a closer look, we can identify these things in common: * extensive use of data types and functions of https://wiki.gnome.org/Projects/GLib[GLib] * Cluster Testing System (CTS) is inherited from initial implementation by Alan Robertson * ... == Notable Restructuring Steps in the Codebase == File renames may not appear as notable ... unless one runs into complicated +git blame+ and +git log+ scenarios, so some more massive ones may be stated as well. * watchdog/'sbd' functionality spin-off: ** https://github.com/ClusterLabs/pacemaker/commit/eb7cce2a172a026336f4ba6c441dedce42f41092[ start separating, eb7cce2a1] ** https://github.com/ClusterLabs/pacemaker/commit/5884db78080941cdc4e77499bc76677676729484[ finish separating, 5884db780] * daemons' rename for 2.0 (in chronological order) ** https://github.com/ClusterLabs/pacemaker/commit/318a2e003d2369caf10a450fe7a7616eb7ffb264[ start of moving daemon sources from their top-level directories under new +/daemons+ hierarchy, 318a2e003] ** https://github.com/ClusterLabs/pacemaker/commit/01563cf2637040e9d725b777f0c42efa8ab075c7[ +attrd+ -> +pacemaker-attrd+, 01563cf26] ** https://github.com/ClusterLabs/pacemaker/commit/36a00e2376fd50d52c2ccc49483e235a974b161c[ +lrmd+ -> +pacemaker-execd+, 36a00e237] ** https://github.com/ClusterLabs/pacemaker/commit/e4f4a0d64c8b6bbc4961810f2a41383f52eaa116[ +pacemaker_remoted+ -> +pacemaker-remoted+, e4f4a0d64] ** https://github.com/ClusterLabs/pacemaker/commit/db5536e40c77cdfdf1011b837f18e4ad9df45442[ +crmd+ -> +pacemaker-controld+, db5536e40] ** https://github.com/ClusterLabs/pacemaker/commit/e2fdc2baccc3ae07652aac622a83f317597608cd[ +pengine+ -> +pacemaker-schedulerd+, e2fdc2bac] ** https://github.com/ClusterLabs/pacemaker/commit/038c465e2380c5349fb30ea96c8a7eb6184452e0[ +stonithd+ -> +pacemaker-fenced+, 038c465e2] ** https://github.com/ClusterLabs/pacemaker/commit/50584c234e48cd8b99d355ca9349b0dfb9503987[ +cib daemon+ -> +pacemaker-based+, 50584c234] //// TBD: - standalone tengine -> part of crmd/pacemaker-controld //// diff --git a/doc/Pacemaker_Development/en-US/Ch-Hacking.txt b/doc/Pacemaker_Development/en-US/Ch-Hacking.txt new file mode 100644 index 0000000000..f26cf6284f --- /dev/null +++ b/doc/Pacemaker_Development/en-US/Ch-Hacking.txt @@ -0,0 +1,68 @@ +:compat-mode: legacy += Advanced Hacking on the Project = + +anchor:ch-hacking[Chapter 6. Hacking on Pacemaker] + +[id="hacking-foreword"] +== Foreword == + +This chapter aims to be a gentle introduction (or perhaps, rather +a summarization of advanced techniques we developed for backreferences) +to how deal with the Pacemaker internals effectively. +for instance, how to: + +* debug with an ease +* verify various interesting interaction-based properties + +or simply put, all that is in the interest of the core contributors +on the project to know, master, and (preferably) also evolve +-- way beyond what is in the presumed repertoire of a generic +contributor role, which is detailed in other chapters of this guide. + +Therefore, if you think you will not benefit from any such details +in the scope of this chapter, feel free to skip it. + +== Debugging == + +In the GNU userland tradition, preferred way of debugging is based +on 'gdb' (directly or via specific frontends atop) that is widely +available on platforms (semi)supported with Pacemaker itself. + +To make some advanced debugging easier, we maintain a script defining +some useful helpers in `extra/gdb/gdbhelpers` file, which you can make +available in the debugging session easily when invoking it as +`gdb -x ...`. + +From within the debugger, you can then invoke the new `pcmk` command +that will guide you regarding other helper functions available, so +we won't replicate that here. + +== Working with mocked daemons == + +Since the Pacemaker run-time consists of multiple co-operating daemons +as detailed elsewhere, tracking down the interaction details amongst +them can be rather cumbersome. Since rebuilding existing daemons in +a more modular way as opposed to clusters of mutually dependent +functions, we elected to grow separate bare-bones counterparts built +evolutionary as skeletons just to get the basic (long-term stabilized) +communication with typical daemon clients going, and to add new modules +in their outer circles (plus minimalistic hook support at those cores) +on a demand-driven basis. + +The code for these is located at `maint/mocked`; for instance, +`based-notifyfenced.c` module of `based.c` skeleton mocking +`pacemaker-based` daemon was exactly to fulfill investigation helper +role (the case at hand was also an impulse to kick off this very +sort of maintenance support material, to begin with). + +Non-trivial knowledge of Pacemaker internals and other skills are +needed to use such devised helpers, but given the other way around, +some sorts of investigation may be even heftier, it may be the least +effort choice. And when that's the case, advanced contributors are +expected to contribute their own extensions they used to validate +the reproducibility/actual correctness of the fix along the actual +code modifications. This way, the rest of the development teams is +not required to deal with elaborate preconditions, be at guess, or +even forced to use a blind faith regarding the causes, consequences +and validity regarding the raised issues/fixes, for the greater +benefit of all. diff --git a/doc/Pacemaker_Development/en-US/Pacemaker_Development.xml b/doc/Pacemaker_Development/en-US/Pacemaker_Development.xml index c02d705c90..888696dc20 100644 --- a/doc/Pacemaker_Development/en-US/Pacemaker_Development.xml +++ b/doc/Pacemaker_Development/en-US/Pacemaker_Development.xml @@ -1,15 +1,16 @@ %BOOK_ENTITIES; ]> - - - - - - - + + + + + + + + diff --git a/doc/Pacemaker_Development/en-US/Revision_History.xml b/doc/Pacemaker_Development/en-US/Revision_History.xml index b9c1dea6ae..32b37341ce 100644 --- a/doc/Pacemaker_Development/en-US/Revision_History.xml +++ b/doc/Pacemaker_Development/en-US/Revision_History.xml @@ -1,95 +1,108 @@ %BOOK_ENTITIES; ]> Revision History 1-0 Tue Jul 26 2016 KenGaillot kgaillot@redhat.com Convert coding guidelines and developer FAQ to Publican document 1-1 Mon Aug 29 2016 KenGaillot kgaillot@redhat.com Add Python coding guidelines, and more about licensing 2-0 Fri Jan 12 2018 KenGaillot kgaillot@redhat.com Drop support for Python 2.6 2-1 Tue Sep 18 2018 JanPokorný poki@redhat.com Start documenting notable evolutionary points 2-2 Fri Dec 7 2018 KenGaillot kgaillot@redhat.com Update FAQ and C guidelines 2-3 Mon May 13 2019 KenGaillot kgaillot@redhat.com JanPokorný poki@redhat.com Update copyright notice policy, and some external references + + 2-4 + Fri 17 May 2019 + + JanPokorný + poki@redhat.com + + + Start capturing hacking howto + for advanced contributors + + +