Update diverser Manpages und Beispiele
Change-Id: I07094305b7697550dac8667a26e150ca23560e41
diff --git a/doc/wiz/regionsleitfaden b/doc/wiz/regionsleitfaden
index 70e491a..45e85f5 100644
--- a/doc/wiz/regionsleitfaden
+++ b/doc/wiz/regionsleitfaden
@@ -44,7 +44,9 @@
Dateien aus den Verzeichnissen.
o Speicherung von Daten in secure-Verzeichnissen soll bitte nur sehr
- sparsam erfolgen und nur in Abstimmung mit dem RM.
+ sparsam erfolgen und nur in Abstimmung mit dem RM. Denkt dabei daran,
+ dass Secure-Verzeichnisse im Zusammenspiel mit Git/Gerrit zusaetzliche
+ Probleme aufwerfen.
o save_object() bitte sehr sparsam verwenden (nicht bei jeder Daten-
aenderung, bei Bedarf in reset/remove).
diff --git a/doc/wiz/rm-howto b/doc/wiz/rm-howto
index 63c9a84..a722c8c 100644
--- a/doc/wiz/rm-howto
+++ b/doc/wiz/rm-howto
@@ -4,10 +4,11 @@
Vorlaeufiges Inhaltsverzeichnis:
1) Allgemeines
+ - Konzepte fuer neue Gebiete
- Fehlerteufel
- - Logtool
- Kommentierung von Aenderungen
- eigene Anschluesse
+ - "Datenhygiene" im Regionsverzeichnis
2) Abnahme von Code/Gebieten
- Balance/Genehmigungen
- Konzeptionelle Eignung
@@ -32,67 +33,116 @@
1) Allgemeines
==============
-o Um stets einen Ueberblick ueber die in Deiner Region (hoffentlich selten)
- auftretenden Bugs und Warnungen zu behalten, solltest Du einen
- Fehlerteufel (/obj/tools/fehlerteufel.c) besitzen, bedienen koennen und
- regelmaessig dessen Listen durchsehen. Deinen Regionsmitarbeitern solltest
- Du, allein schon, um zusaetzliche Arbeit fuer Dich selbst zu reduzieren,
- dieses Werkzeug ebenfalls an die Hand geben und sie auffordern, ihren
- Kram moeglichst umfassend selbst zu reparieren.
- Neuen Magiern wird dieses Tool uebrigens automatisch von Merlin in die
- Hand gedrueckt, so dass sie sich vom ersten Tag an daran gewoehnen koennen.
+1a) Konzepte und Dokumentation
-o Es ist empfehlenswert, das Logtool zu besitzen (/obj/tools/logtool.c) und
- in diesem fuer jedes Repfile eines Regionsmitarbeiters einen Eintrag vor-
- zusehen. Warum das? Es ist bereits vorgekommen, dass Spieler ernsthaft
- argumentiert haben, sie duerften einen von ihnen entdeckten Bug ausnutzen,
- weil sie ihn ja gemeldet haetten (im Repfile!), er aber nicht repariert
- worden sei (was nicht verwundert, da er im Repfile in der Mehrzahl der
- Faelle weit unterhalb des Wahrnehmungshorizonts der allermeisten
- Regionsmagier schwebt).
+ o Die Erfahrung zeigt, dass es aus verschiedenen Gruenden wirklich dringend
+ zu empfehlen ist, sich fuer neue Gebiete ein Konzept vorlegen zu lassen,
+ dieses gruendlich zu pruefen und zu durchdenken und mit dem betreffenden
+ Regionsmitarbeiter zu diskutieren. Weiterhin empfiehlt es sich ebenfalls,
+ eine ueber das Konzept erzielte Einigung im Verzeichnis "doc" Deiner
+ Region zu dokumentieren. Hierdurch erreichst Du mehrere Dinge:
+ - Du vermeidest Ueberraschungen ("Hier ist mein neues Gebiet zur Abnahme,
+ sind nur 120 Raeume. Oh, hoppla, hab ich Dir nicht Bescheid gesagt?");
+ auch fuer Deine etwaigen Nachfolger.
+ - Du vermeidest bei absehbaren technischen Schwierigkeiten Frustration
+ beim Deinem Regionsmitarbeiter.
+ - Du erhoehst die Wahrscheinlichkeit, dass das Gebiet tatsaechlich
+ fertiggestellt wird.
+ - Jeder kann weitgehend verbindlich nachlesen, was Du genehmigt hast.
+ - Es ist klar ersichtlich, welche Konzepte bekanntermassen schon in Arbeit
+ sind, so dass inhaltliche Aehnlichkeiten im Vorfeld vermieden werden
+ koennen.
+
+ Du solltest den betreffenden Regionsmitarbeiter auch darauf hinweisen,
+ dass er Dich informieren moege, wenn er eine groessere konzeptionelle
+ Umstellung des neuen Gebietes durchfuehren will.
-o Wenn Du in fremdem Code Aenderungen vornehmen musst, die mehr beruehren
- als nur ein paar Tippfehler in Details oder Infos, dann kommentiere den
- defekten Code aus und fuege den reparierten mit Kommentar ein. Es reicht
- an dieser Stelle aus, Deinen Namen und das Datum zu vermerken. In den
- Header der Datei solltest Du unbedingt ein Changelog einfuegen, in dem
- das Datum der Aenderung, der Name des Ausfuehrenden (Deiner) sowie die
- vorgenommene Aenderung mit Begruendung bzw. u.U. Bug-ID aus dem Fehler-
- teufel einzutragen ist. Wir haben im MG leider keinen wirkungsvollen
- Debugger und Bugtracker-Mechanismus, so dass wir zur Erhaltung einer
- gewissen Code-Hygiene Bugfixes mit Hilfe solcher Eintragungen dokumentieren
- und rueckverfolgen muessen. Insbesondere ist ein solcher Eintrag wichtig,
- um im Falle von Folge-Bugs die Ursache schneller zu finden.
+ Welche Kriterien man als RM ansetzt, um ein Gebiet als regionstauglich
+ zu bewerten, liegt in der Entscheidung des RM.
-o Willst Du in Deiner eigenen Region ein Gebiet anschliessen, solltest Du
- diesen vor Anschluss entweder vom Co-RM oder von einem RM einer anderen
- Region lesen lassen. Auch wenn Du ein guter Programmierer bist, findet ein
- zweites Paar Augen oft Dinge, an die man nicht gedacht hat.
+ o Wenn ein Konzept fuer ein Gesellenstueck eingereicht wird, und es handelt
+ sich um eine Gemeinschaftsarbeit mehrerer Magier (Kooperation mehrerer
+ Lehrlinge oder Lehrling(e) + erfahrene Magier), UEBERLEGT EUCH GUT, OB
+ IHR DAS ZULASSEN WOLLT! Erfahrungsgemaess laesst sich schwer beurteilen,
+ welcher Teil des Codes von wem ist. Wenn es zugelassen wird, sollten mit
+ den betreffenden Lehrlingen klare Vereinbarungen insbesondere ueber die
+ Trennung des Codes nach Autor getroffen werden.
+1b) Fehlerteufel / Abarbeitung von Bugs
+
+ o Um stets einen Ueberblick ueber die in Deiner Region (hoffentlich selten)
+ auftretenden Bugs und Warnungen zu behalten, solltest Du einen
+ Fehlerteufel (/obj/tools/fehlerteufel.c) besitzen, bedienen koennen und
+ regelmaessig dessen Listen durchsehen. Deinen Regionsmitarbeitern solltest
+ Du, allein schon, um zusaetzliche Arbeit fuer Dich selbst zu reduzieren,
+ dieses Werkzeug ebenfalls an die Hand geben und sie auffordern, ihren
+ Kram moeglichst umfassend selbst zu reparieren.
+ Neuen Magiern wird dieses Tool uebrigens automatisch von Merlin in die
+ Hand gedrueckt, so dass sie sich vom ersten Tag an daran gewoehnen
+ koennen.
+
+ o Wenn Du in fremdem Code Aenderungen vornehmen musst, die mehr beruehren
+ als nur ein paar Tippfehler in Details oder Infos, dann fuege den
+ reparierten Code mit Kommentar ein. Wenn in Deiner Region git/gerrit zur
+ Codeverwaltung verwendet werden, schreibe eine aussagekraeftige Commit-
+ Message, bei Bedarf ergaenzt durch einen Kommentar im Code.
+
+1c) Anschluss eigener Gebiete in der eigenen Region
+
+ o Willst Du in Deiner eigenen Region ein Gebiet anschliessen, solltest Du
+ diesen vor Anschluss entweder vom Co-RM oder von einem RM einer anderen
+ Region lesen lassen. Auch wenn Du ein guter Programmierer bist, findet ein
+ zweites Paar Augen oft Dinge, an die man nicht gedacht hat.
+
+1d) "Hygiene" in den Regionsverzeichnissen
+
+ o Wenn Du nicht angeschlossene Objekte aus Deiner Region aussortieren
+ moechtest, ist sprich am besten einen EM an, der Dir dabei hilft:
+ Einerseits kann man auf der Shell bequemer herausfinden, ob ein Objekt
+ tatsaechlich nicht verwendet wird. Andererseits soll der ungenutzte
+ Code in das /players-Verzeichnis des Autors verschoben werden, was
+ haeufig ebenfalls EM-Rechte benoetigt.
+
+ o Es wird dringend empfohlen, neuen Regionscode nur noch in /players zu
+ entwickeln.
+
+ o Als Regionsmagier hast Du aufgrund eines EM-Beschlusses die Moeglichkeit,
+ fuer Deine jeweilige(n) Region(en) verbindlich festzulegen, ob es erlaubt
+ ist, die Entwicklung neuer Gebiete im Regionsverzeichnis durchzufuehren.
+
2) Code wird zur Abnahme vorgelegt
==================================
-o Bei Waffen und Ruestungen unbedingt auf Einhaltung der Balance-Vorgaben
- achten.
+o Bei Waffen und Ruestungen unbedingt darauf achten, dass Objekte, die die
+ Genehmigungsgrenzen ueberschreiten, bei der Balance zur Genehmigung
+ vorgestellt wurden. Fuer alle Objekte mit Balance-relevanten Eigenschaften
+ bitte penibel darauf achten, dass die Balance-Vorgaben eingehalten werden.
+ Jeder Magier kann sich ein Balance-Tool "light" clonen, mit dem er den Text
+ der Genehmigung selbst anschauen kann, um den vorgelegten Code damit zu
+ vergleichen. Nicht genehmigte oder in der Funktion abweichende Objekte
+ duerfen nicht angeschlossen werden. (Bei schon sehr lange angeschlossenen
+ Objekten, deren Abweichung von der Genehmigung erst sehr spaet auffaellt,
+ kann man ggf. auf das temporaere Abhaengen verzichten.)
o Sofern ein Objekt eine Balance-Genehmigung besitzt, muss die BTOP-Nummer,
die die Balance als eindeutige ID fuer jeden Antrag vergibt, im Header
- des betreffenden Objektes erkennbar eingetragen sein.
+ des betreffenden Objektes erkennbar eingetragen sein. Bevorzugt traegt
+ man auch die genehmigten Eigenschaften ein.
-o Vor Anschluss sollte man Ruecksprache mit verschiedenen Instanzen halten,
- um sicherzustellen, dass der Magier alle wesentlichen Punkte
- beruecksichtigt hat:
- - liegen alle Balance-Genehmigungen vor?
- - sind die FP eingetragen?
- - sind die ZTs eingetragen und getestet?
- - sind Sonder-EK-Stupse genehmigt und eingetragen?
-
-o Fuer neue Gebiete ist eine grundsaetzliche Pruefung des Konzepts auf
- Regionstauglichkeit sinnvoll, damit nicht alteingesessene Institutionen
- oder Orte ploetzlich zur zweiten Wahl abgewertet werden - beispielsweise
- einen grossen, neuen Hauptort in der Ebene anzuschliessen, der Port Vain
- voraussehbar den Rang ablaufen wuerde.
+o Vor Anschluss sollte man kontrollieren, dass der Magier alle wesentlichen
+ Punkte beruecksichtigt hat:
+ - Liegen alle Balance-Genehmigungen vor?
+ BTool light gibt's fuer alle, damit kann jeder fuer Objekte in seinem
+ Zustaendigkeitsbereich die Genehmigungen einsehen.
+ - Sind die FP eingetragen?
+ FP kann der RM fuer das neue Gebiet selbst abfragen.
+ - Sind die ZTs eingetragen und getestet?
+ Dies laesst sich mit dem Magierkommando "traenke" herausfinden.
+ - Falls Sonder-EK-Stupse vorgesehen sind: sind diese genehmigt?
+ Die Eintragung bzw. Anpassung der Stufenpunkte fuer den Kill wird
+ erledigt, sobald der NPC das erste Mal getoetet wurde, dies muss also nicht
+ ueberprueft werden.
o Alle NPCs sollten vor Anschluss einmal gekillt werden, um sie auf
grundsaetzliche Kampf-Funktionsfaehigkeit zu pruefen.
@@ -104,24 +154,26 @@
Formfehler in einem kompletten Verzeichnis ermitteln kann (Umlaute im
Code, zu lange Zeilen etc.), wobei bezueglich der Formalien auch auf
den Regionsmitarbeiter-Leitfaden fuer neue Projekte verwiesen werden
- soll. Das Skript hierzu ist auf Anfrage bei Zesstra erhaeltlich. Der
- Regionsmagier hat hierbei die Entscheidungsfreiheit, die Berichte dieses
- Skripts dem Programmierer des neuen Gebiets als Anhaltspunkte zur
- Verfuegung zu stellen, oder die Abarbeitung der gemeldeten Punkte als
- Voraussetzung vor dem Anschluss vorzuschreiben, aber auch jede Abstufung
- dazwischen ist OK. :-)
+ soll. Das Skript liegt im oeffentlichen Git-Repo "static-lpc-check" auf
+ dem MG-Gerrit-Server. Man kann es mit git oder ueber das Webinterface
+ herunterladen. Der Regionsmagier hat hierbei die Entscheidungsfreiheit,
+ die Berichte dieses Skripts dem Programmierer des neuen Gebiets als
+ Anhaltspunkte zur Verfuegung zu stellen, oder die Abarbeitung der
+ gemeldeten Punkte zur Voraussetzung fuer den Anschluss zu machen, aber
+ auch jede Abstufung dazwischen ist OK. :-)
Zusaetzlicher Tip: Das Skript differenziert zwischen eigentlich nicht
akzeptablen Konstrukten und zumindest fragwuerdigen, d.h. man kann diese
Unterscheidung an den Verantwortlichen mit entsprechenden Forderungen
weitergeben.
- Das Skript ist unter ftp://mg.mud.de/Software/src_check/ erhaeltlich.
-o Sollte ein zur Abnahme anstehendes Projekt eine (grundsaetzlich
+o Sollte ein zur Abnahme anstehendes Gesellenstueck eine (grundsaetzlich
selbstverstaendlich zulaessige) Gemeinschaftsarbeit sein, sollte man
- als Regionsmagier darauf bestehen, eine sauber getrennte Codebasis
- in unterschiedlichen Verzeichnissen vorgelegt zu bekommen, oder aber
- eine Auflistung, welcher Beitrag von welchem Magier stammt.
- Wenn diese Auflistung sich bis auf Funktionsebene erstrecken sollte
+ darauf bestehen, eine sauber getrennte Codebasis in unterschiedlichen
+ Verzeichnissen vorgelegt zu bekommen, oder aber eine Auflistung, welcher
+ Beitrag von welchem Magier stammt. Es sollte klar sein, dass die
+ Beurteilung der Faehigkeiten eines Lehrlings darauf angewiesen ist, dass
+ man den Code richtig zuordnen kann.
+ Wenn eine solche Auflistung sich bis auf Funktionsebene erstreckt
(z.B. "DoWield() ist von X, Details von Y, DefendFunc von Z"), ist
das unschoen und an sich abzulehnen.
@@ -215,7 +267,7 @@
{
pl = find_player(lower_case(name1));
if (!pl || !living(pl))
- return 1;
+ return;
else
Kill(pl);
}
@@ -296,13 +348,10 @@
o for()-Schleifen
Eigentlich keine Funktion, aber an dieser Stelle doch passend:
for()-Schleifen sollten generell durch foreach()-Konstruktionen ersetzt
- werden, da dies signifikant und messbar schneller ist. Die naechst-
- schnellere Variante waere etwa folgendes, sofern die Reihenfolge der
- Abarbeitung unerheblich ist (i ist integer, arr ist ein mixed-Array):
-
- for ( i=sizeof(arr); i--; ) {
- tu_etwas_mit(arr[i]);
- }
+ werden, da dies signifikant und messbar schneller ist. Der groesste
+ Zeit- und Kostenfaktor ist die Verwendung von sizeof() als Abbruchkriterium
+ in einer for()-Schleife. Wenn sich die Schleife also nicht ersetzen laesst,
+ dann nehmt zumindest einen konstanten Wert als Abbruchkriterium.
o write_file()
Benutzung dieser Funktion nur in begruendeten Ausnahmefaellen abnehmen, da
@@ -311,6 +360,10 @@
verbrauchen, aber kaum zu ueberschauen sind. Statt write_file() wird in
den allermeisten Faellen log_file() mit der Standardgroesse von 50 kB fuer
Logfile und eine ggf. vorhandene Altversion (*.OLD) ausreichend sein.
+ Standardmaessig ist das Schreiben eines Questlog-Eintrages in /log/quest
+ der einzige Einsatzzweck, wo write_file() wirklich notwendig ist.
+ Ansonsten sind Ausnahmen vorstellbar, wenn die neuen Daten die alte Datei
+ komplett ersetzen, d.h. nicht angehaengt werden.
o Verwalten von charakterbezogenen Daten
Als Beispiel seien hier Statusdaten fuer den Ablauf von Quests genannt,