wiki:GetInvolved/Trac
Last modified 3 years ago Last modified on 11/11/2013 10:52:39 AM

Trac

Pri razvoju in za same vsebine spletne strani wlan slovenija omrežja se uporablja Trac, ki je spletna aplikacija za organizacijo projektov. Njegovi glavni funkcionalnosti sta wiki in ticketi.

Vso vsebino na spletni strani pišemo v slovenščini s šumniki, kjer pa ne pretiravamo s slovenjenjem redko uporabljanih računalniških izrazov. Določene vsebine prevajamo v tuje jezike v področju International?.

Novi uporabniki

Priporočeno je, da si novi uporabniki nastavijo podatke svojega uporabniškega imena. To storimo tako, da pod Preferences izpolnimo polje Email address, lahko pa tudi Full name. Na naslov, ki ga vnesemo, kasneje po privzetem prejemamo obvestila o ticketih, ki smo jih odprli ali sprejeli (kar lahko tam tudi izklopimo, možnost Ticket notifications opt-out). Prav tako služi za prejemanje obvestil o delovanju točk?, na katera se prijavimo, in nanj dobimo tudi zgenerirane image?.

Wiki

Wiki je zbirka opisov, razlag, navodil in dokumentacije ter drugih podatkov, ki vsi skupaj predstavljajo omrežje in pomagajo pri njegovem razvoju in rasti. Spletna stran wlan slovenija omrežja je v ozadju wiki sistem, kar pomeni, da jo podobno kot Wikipedijo lahko ureja vsak.

S sodelovanjem in skupinskim pisanjem vsebin in navodil tako raste tudi spletna stran. Podobno kot s sodelovanjem raste tudi omrežje? samo.

Pripenjanje fotografij in drugega slikovnega gradiva

Trenutno (#150 in #151) je pripenjanje slik mogoče malo zamudno opravilo, saj ni avtomatizirano, ampak po drugi strani to vpliva na objavljanje le kvalitetnih slik.

Tako je potrebno vsako sliko, za katero želimo na strani prikazati tudi manjšo verzijo in jo prikazati v JavaScript galeriji, pripeti dvakrat, original in malo verzijo. Te male slike naj bodo 200xnekaj px oziroma nekajx200 px, torej obe stranici naj bosta največ 200 px. Mala verzija panoramskega posnetka pogleda s točke? pa naj bo široka 600 px. Tudi originalom ni potrebno, da so preveliki, 1000 px najdaljša stranica je večinoma zadosti.

Skripti, ki podane slike pomanjšata na zgoraj opisane velikosti, sta pripeti na koncu te strani.

Pri pripenjanju je dobro napisati komentar k sliki, tako pri originalu kot mali verziji, saj se slednji izpiše v JavaScript galeriji, prvi pa pri ogledu slike na samostojni strani. Prav tako se ta komentar uporabi za alternativni opis slike v primeru tekstovnih brskalnikov (ki ga uporabijo tudi iskalniki).

Ko so slike pripete, jih je potrebno vstaviti na ustrezno mesto s takšnim ukazom:

[[Image(ime-datoteke-small.jpg, link=attachment:ime-datoteke.jpg, border=1)]]

V primeru zaporedja več slik preprosto naštejemo zgoraj opisani ukaz večkrat, ločen s presledkom in z ustreznimi imeni datotek.

JavaScript galerija avtomatsko prepozna tako vstavljene slike.

Link to the node database

Link the node database can be easily made with a Trac link with prefix nodes. Examples:

[nodes: node database]
[nodes:nodes/statistics network statistics]
[nodes:node/reis-node/#graph-memory-usage memory usage statistics]

Simply anything after : is appended to the base URL of the node database installation.

Link to a message on the mailing list

Link to a message in the archive of a mailing list can be done with a Trac link as well. In this case prefix lists should be used with additional parameters which determine the specific message: name of the mailing list, year of the archive, month of the archive, and a serial number of the message in that month. Example of a link to this message can thus be done like:

[lists:talk:2010:03:00030 message]

Link to another Trac installation

To make link to another Trac installation you just prefix the link you would use on that Trac with the prefix for that Trac. For example:

[grow:ticket:123 #123]
[grow:comment:1:ticket:123 1st comment of the ticket 123]

See the list of linked Trac installations for possible prefixes.

Link to wlan slovenija homepage

Links to wlan slovenija homepage can be done with prefix wlansi:

[wlansi:contact contact page]

As with other prefixes, simply anything after : is appended to the base URL of the homepage.

Link to GitHub

Links to wlan slovenija GitHub can be done with prefix github:

[github:nodewatcher nodewatcher repository]

Link to EtherPad pads

To link a particular pad you can use prefix pad:

[pad:ICFEzvmdzf some pad]

Link to nodewatcher documentation

[nodewatcher: nodewatcher documentation]

Link to Wikipedia definitions

[wikipedia:Wlan_slovenija wlan slovenija Wikipedia page]

Slovenian Wikipedia:

[slwikipedia:Wlan_slovenija Slovenian Wikipedia]

There are many other similar ways to create Trac links. See list of possible prefixes.

Ticketi

Ticketi opisujejo opravila oziroma napake, ki jih je potrebno narediti oziroma razrešiti pri delu na wlan slovenija omrežju. Pomagajo nam pri organizaciji dela.

Razvrščamo jih lahko na dva načina. Prvi je po milestonih (časovnih mejnikih). Te najdemo pod roadmap. Milestoni služijo za časovno razporeditev dela. Ticketu lahko določimo tudi komponento. To je področje projekta, kamor opravilo oziroma napaka sodi in tako lahko razvrščamo tickete tudi po njih.

Ticketi imajo tudi možnost komentiranja; tako se lahko sodeluje pri iskanju rešitve problema oziroma se dela na opravilu. Tisti, ki dela na ticketu, lahko komentira, na kakšne težave je naletel, kako jih je rešil, pokomentira svoje odločitve, na koncu pa napiše še, kako je na koncu naredil, da ostane opravilo oziroma odprava napake podokumentirana.

Pregled ticketov

Tickete lahko vidimo pod opravila, napake. Najpogosteje nas bodo zanimali odprti ticketi, ki jih vidimo, če izberemo Active Tickets by Milestone, to so ticketi, ki jih je še potrebno opraviti na časovno obdobje. Na desnem zgornjem meniju lahko vidimo tudi Custom Query. Ta služi za filtriranje ticketov. Pod Custom Query lahko recimo dodamo filter Component in izberemo željeno področje projekta. Podobno lahko dodamo še filter Status in obkljukamo vse razen Closed (več o stanjih ticketov v nadaljevanju). Tako nam iskalnik pokaže vse odprte tickete (opravila), ki se jih mora narediti za izbrano področje. Filtre lahko poljubno nastavljamo, da najdemo željene tickete.

Sprejemanje ticketov

Sprejeti ticket pomeni sprejeti opravilo. Ticket lahko sprejmemo, če ga ni sprejel že kdo drug, razen če se dogovorimo s tistim, ki ga je že sprejel. Ticket sprejmemo tako, da ga odpremo (kliknemo nanj) ter nato spodaj označimo polje Accept in kliknemo Submit changes.

Komentiranje ticketov

Tickete lahko komentiramo v polju Comment. Opisa ticketa nikoli ne spreminjamo! (Razen v primeru manjših popravkov, ki ne spremenijo vsebine oziroma pomena opisa. Recimo slovničnih napak, nepravilnih oziroma nedelujočih povezav in drugih napak pri opisu.) Tega ne počnemo zato, da se vidi kaj je bilo potrebno narediti, kaj je bilo izhodišče, saj se le tako lahko pregledno beleži potek dela. Če je potrebno kaj dodati, napišemo to v komentar. O slogih besedila v komentarjih si lahko več preberemo tukaj. Enako se ureja besedilo povsod na Tracu – v opisih ticketov, v dokumentaciji ... Vprašanja in težave, na katere smo naleteli med opravljanjem ticketa, se zapišejo v komentar, da se skupaj z najdenimi rešitvami ne izgubijo. Ko napišemo ustrezen komentar, ga preverimo s Preview in zatem objavimo s klikom na Submit changes.

Zapiranje ticketov

Ticket lahko zapremo, ko smo dokončali opravilo oziroma razrešili problem. Pred zaprtjem je treba napisati zaključni komentar, ki povzema, kaj je bil vzrok problema (v kolikor tega ni v opisu ticketa), kako se je prišlo do rešitve in kakšna je ta rešitev. Mogoče se poda tudi navodila za splošno odpravljanje podobnih problemov. Ko smo ticket primerno pokomentirali, spodaj nastavimo Resolve as na eno od možnih vrednosti.

  • fixed: opravilo je bilo opravljeno; v kolikor je s tem povezana kakšna sprememba v repozitoriju?, se v zaključni komentar napiše, s katero revizijo oziroma revizijami v repozitoriju? je ticket povezan, vsaka v obliki [123]
  • worksforme: problem oziroma napaka ni v resnici problem, že deluje oziroma je na voljo na drugačen način
  • wontfix: problem oziroma napaka ni res naš problem
  • invalid: ticket je bil test, je bil napačno odprt ...
  • duplicate: že obstaja ticket z enakim oziroma zelo podobnim opravilom; v tem primeru je potrebno v duplikatu napisati v zaključni komentar This ticket is duplicate of #1234. in v originalnem #4321 was marked as duplicate of this ticket.; prav tako pa se v originalni ticket doda v Cc polje avtorja duplikata, tako da bo obveščen o razvoju originalnega ticketa

Na koncu preverimo vnešene podatke s Preview in zatem potrdimo s Submit changes.

Special options

There are two special options when finishing work on a ticket. They determine that in order to close a ticket two conditions need to be met:

  • that the system the nodes' base is running on, is updated with new changes in the repository? with the option mark for nodewatcher update; hereby it is recommended to state in the ending comment whether the data scheme needs to be updated along the software update
  • the image? generator needs to be updated, because firmware changes have been added into the repository?, with the option mark for image generator rebuild

The ending comment with one of these special options is to be written in the usual way.

Opening tickets

When we run into a problem, or we notice something has not been finished, yet, we check whether a ticket for this already exists. If it doesn't, we open one. We do this as well if we are solving the problem ourselves, so what we have done is evident. Fields that need to be filled in when creating a ticket are:

  • Summary: a meaningful, short summary of the issue that should contain key words
  • Description: tukaj podrobneje napišemo, kaj je problem oz. kaj je potrebno narediti; besedilo oblikujemo na enak način kot pri komentiranju ticketov
  • Priority: izberemo nujnost opravila
    • blocker nastavimo, če ne moremo delati naprej, dokler to ni narejeno
    • critical nastavimo, če je opravilo zelo pomembno, a ne ovira nadaljnjega dela
    • major nastavimo, če je opravilo srednje pomembno
    • minor nastavimo, če je opravilo manj pomembno
    • trivial nastavimo, če opravilo ni pomembno, a bi vseeno moralo biti narejeno
  • Milestone: nastavimo, če se da smiselno izbrati časovno obdobje, v okviru katerega mora biti opravilo narejeno
  • Component: tukaj izberemo področje, kamor sodi ticket; če ni smiselnega področja za opravilo nastavimo ostalo; ticketi, ki spremljajo postavitve novih točk, sodijo pod področje točke (pri teh je treba izpolniti še polje Related nodes)
  • Version: v kolikor gre za poročilo o napaki pri konkretni izdani verziji, tu izberemo verzijo, sicer pustimo prazno
  • Keywords: vpišemo ključne besede, kar so ponavadi kakšne oznake s posebnim pomenom za obdelavo ticketov; več ključnih besed se loči z vejico
  • CC: tukaj napišemo uporabniška imena oziroma e-mail naslove oseb, ki naj bodo obveščene o nastanku in spremembah ticketa; lastnik, ustvarjalec in prijavljeni na poštni seznam so avtomatsko obveščeni o spremembah
  • Related nodes: tu naštejemo imena točk, ki so povezana s tem ticketom (recimo, če govorimo o težavah s konkretno točko); več točk se loči z vejico
  • Sensitive: v kolikor gre za ticket, ki opisuje težavo ali napako, povezano z varnostjo omrežja ali njegovega delovanja, oziroma bi lahko prost dostop do informacij v nem na splošno ogrozilo uporabnike ali omrežje, se označi to polje, kar bo ticket naredilo dostopen le razvijalcem
  • Blocking: sem napišemo ID morebitnega ticketa, ki bi ga naš ticket oviral; torej če neko opravilo ne more biti narejeno, dokler naš ticket ne bo zaprt, napišemo sem ID tega ticketa
  • Blocked by: podobno kot zgoraj, sem napišemo ID ticketa, zaradi katerega naše opravilo ne more biti narejeno
  • Assign to: tukaj lahko izberemo osebo, v kolikor želimo opravilo komu predlagati
  • Realization state, when used in a ticket for node deployment:
    • idea, wish = where we would like to have a node, but no one has contacted anyone, yet
    • offer = someone contacted us and expressed a wish to set up a node
    • innitial contact = we responded, collected information, inquired what was going on, checked the location, took photos on site, we have all the starting material we need start working (the concept, what needs to be done is set here)
    • coordination = when it comes to action, we set an appointment, buy the equipment, arrange the paperwork
    • testing = we test whether the location is OK, eg. testing equipment is set to see if the equipment is appropriate and if the location is suitable
    • `realization = when we actually go to the location to set up the node, this is the point when we usually close the ticket
    • maintenance = usually needs to be done on working nodes if something breaks down; a new ticket is opened, indicated what happened (if what went wrong, is already known; in case it isn't, the problems are determined as the ticket progresses and plans to resolve the problems are made)

V kolikor smo pripravili kakšen patch za izvorno kodo in bi ga radi posredovali v pregled in morebitno vključitev v izvorno kodo, ki jo uporabljamo pri wlan slovenija omrežju, ga lahko pripnemo ticketu. Zavedati pa se moramo, da s tem, ko ga pripnemo, ob tem, da svojo kodo javno in prosto dostopno objavimo, slednjo tudi dovolimo uporabljati v izvorni kodi wlan slovenija omrežja in v vseh drugih primerih, ki bi posredno ali neposredno uporabili to pripeto izvorno kodo. V praksi to pomeni, da se odpovemo pravicam do pripete izvorne kode in jo dovolimo uporabljati drugim.

Za predogled ticketa kliknemo Preview, za objavo pa Create ticket.

Za pomoč pri odpiranju ticketov si lahko pogledamo že narejene tickete, da dobimo lažjo predstavo o tem, kako naj ticket zgleda.

Obveščanje o spremembah ticketov

Po privzetem so o spremembah ticketov obveščeni lastnik ticketa, ustvarjalec ticketa in našteti na CC seznamu. V kolikor želimo biti obveščeni o spremembah konkretnega ticketa, se lahko tako dodamo na njegov CC seznam. V kolikor pa želimo biti obveščeni o vseh spremembah vseh ticketov, pa je za to na voljo poštni seznam, na katerega se pošiljajo vsa obvestila.

V kolikor pa ne želimo prejemati nobenih obvestil o spremembah, se lahko odjavimo pod Preferences z možnostjo Ticket notifications opt-out. Odjava je priporočena tudi za vse, ki se prijavijo na poštni seznam, saj bodo sicer dobivali nekatera obvestila dvakrat. (Odjava pod Preferences ne vpliva na prejemanje obvestil preko poštnega seznama.)

Attachments