Blog de la Biblioteca de Matemàtiques i Informàtica


Deixa un comentari

Com i per què s’hauria de citar el programari?

Imatge de NeKoKaWaii-chan, sota llicència CC-BY-SA
Imatge de NeKoKaWaii-chan, sota llicència CC-BY-SA

En no existir un estàndard europeu que normalitzi la forma de construir cites bibliogràfiques de llenguatges de programació, codi font, programari, biblioteques, etc. ―l’equivalent a la UNE-ISO 690:2010― algunes organitzacions relacionades amb programari de recerca, com el Software Sustainability Institute o Force11, han començat a definir les bases del que hauria d’observar aquest estàndard. Col·laboren en la detecció, comunicació i recollida de propostes que permetin descriure i citar el producte utilitzat en la investigació, de manera objectiva i útil.

Presentem tres articles que marquen les recomanacions més acceptades entre els professionals del sector.

Jackson, Mike. How to cite and describe software. A: Software Sustainability Institute. [201?]. URL: https://www.software.ac.uk/how-cite-software. [Consultat el 17/09/2018]

Existeix una gran diferència entre descriure quines font d’informació i de referència s’han fet servir per elaborar un projecte i citar-les adequadament. Si parlem de codi, programari, biblioteques, llenguatge, etc. com a font d’informació, aquesta diferència marca la possibilitat de poder accedir a la versió de programari correcta i a les eines i components adequats, que permetran reproduir i/o desenvolupar el projecte al que donen crèdit i, d’aquesta manera, validar-lo. Tota cita normalitzada hauria d’observar la inclusió de camps que ajudin a accedir i descarregar o obtenir tot aquell producte que juga un paper bàsic en un projecte o n’ha proporcionat una novetat substancial.

10 consells per descriure el programari utilitzat en la recerca:

  1. Descriure de forma detallada qualsevol producte informàtic que hagi contribuït a quelcom exclusiu, per tal de poder fer entendre el que s’ha fet, donar la possibilitat de repetir el projecte, i validar i reutilitzar la recerca.
  2. Escollir, entre les diferents opcions, la més adient per descriure el programari que heu utilitzat: notes a peu de pàgina, agraïments, seccions de mètodes i apèndixs…
  3. Tenir en compte si el producte té algun tipus de llicència que obligui a atribuir l’ús del programari a la vostra publicació.
  4. Citar documents que descriguin el programari com a complement, i no com a substitutiu, citant el propi programari.
  5. En el primer esborrany d’un document, posar sempre les cites del programari en referències o bibliografies.
  6. Estar preparats per debatre amb els revisors per què heu citat el programari: voleu reconèixer la contribució dels autors del programari i el valor del programari com a resultat legítim de la recerca.
  7. Informar als revisors si s’està obligat legalment a citar el programari a causa d’una clàusula a la llicència del programari.
  8. Si un avaluador no està d’acord amb una cita de programari formal, es pot fer una referència general al programari del document.
  9. És possible que les cites recomanades no tinguin prou informació per descriure amb precisió el programari que s’ha utilitzat, és possible que calgui afegir més detalls.
  10. Si el programari té un DOI (identificador d’objecte digital), utilitzar-lo per citar el programari. Si el programari té el seu propi lloc web, referenciar l’URL del lloc web per a la cita.

Daniel S. Katz, Neil P. Chue Hong . Software Citation in Theory and Practice. A: Arxiv.org. Publicat el 21 de juliol de 2018. URL: https://arxiv.org/abs/1807.08149. DOI: arXiv:1807.08149. [Consultat el 17/09/2018]

Force11 és un col·lectiu format per professors, bibliotecaris, investigadors i editors, organitzat per facilitar la millora en la creació i la transferència de coneixement mitjançant l’ús efectiu de la tecnologia de la informació. Force11 s’organitza en diferents comunitats, una de les quals treballa per desenvolupar un paquet de principis que permeti citar correctament codi font, programa i programari, per tal de poder incloure les cites dins del sistema demanat per les publicacions. Els seus objectius són:

  • Promoure la idea de la importància de citar aquests recursos entre els desenvolupadors i els usuaris.
  • Col·laborar amb els editors per assegurar que aquest sistema reculli les metadades necessàries perquè puguin ser indexades.
  • Treballar de forma comunitària per tal d’enfortir el paper del codi font, programa i programari, com a font d’informació equivalent a les bibliogràfiques (inclús aquell producte que no està publicat).
  • Garantir la qualitat de la informació acreditant el programari mitjançant cites.

La base per poder dur a terme aquesta tasca és desenvolupar un sistema de citació que serveixi per a tot tipus de producte. Aquesta és la raó per la qual el grup “Software Citation” ha treballat produint una infraestructura en forma de directriu. Són els Principis de Citació (Citation Principles), que abasten sis estàndards, contemplats com a punts imprescindibles de tota citació:

  1. Importància: el producte citat ha de ser considerat un producte legítim en la investigació.
  2. Crèdit i Atribució: les cites han de facilitar el crèdit acadèmic i l’atribució normativa. Ha de ser legal de cara a tots els contribuents: inclou autors, contribuïdors o el nom del projecte si aquests es desconeixen.
  3. Identificació unívoca. Per exemple, un DOI o URL: mètodes identificadors interoperables, llegibles per màquina i universals.
  4. Persistència: els identificadors únics i les metadades que descriguin el producte han de ser persistents.
  5. Accessibilitat: les cites han de servir per facilitar l’accés al producte i a les metadades associades.
  6. Especificitat: les cites han d’indicar quina versió del producte s’ha utilitzat. Han d’incloure el nom del producte, el número de versió o la data d’alliberament.

Consulteu a l’article com construir cites que respectin aquests 6 principis.

Wilson, Robin. Encouraging citation of software – introducing CITATION files. A: Robin’s Blog, 30 d’agost de 2013. URL: http://blog.rtwilson.com/encouraging-citation-of-software-introducing-citation-files/. [Consultat el 17/09/2018]

Sobre la importància d’incloure al projecte un fitxer que contingui les indicacions per saber com citar el codi que s’ha creat. L’arxiu CITATION no conté altra cosa que les indicacions a seguir per què d’altres citin codi inclòs: autor original, títol del projecte associat, nom del codi, versió, data, i el nom i URL del repositori on està emmagatzemat. Per què s’haurien de perdre dos minuts en incloure un arxiu CITATION? Perquè un cop elaborat el codi pel projecte i dipositat al DD (o no), potser cal tornar-lo a fer servir per a un altre projecte, o una altra persona el vol treballar. Potser l’has dipositat a GitHub i des d’aquí és fàcil obtenir una cita al teu codi), però afegir un arxiu CITATION facilita que obtinguis el crèdit i reconeixement a la teva feina.


Deixa un comentari

Cerques guiades: GitHub

GitHubGitHub, amb 6 milions d’usuaris registrats, és una xarxa de desenvolupament de programari per mitjà d’una comunitat virtual i distribuïda (o social coding ) que, alhora, funciona com a servei d’allotjament de fitxers. En un origen tenia per objectiu el control de versions, però actualment abasta entorns de gestió del cicle de vida d’aplicacions, i inclou altres elements de caire social en una plataforma única i integrada (Hub). D’una banda anima a la discussió i a compartir i, de l’altra, funciona com a repositori. Ofereix l’opció de treballar des del navegador o des de l’aplicació d’escriptori.

Per tal de contribuir, descarregar i aportar contingut cal estar registrat. Abans de fer-ho, però, s’ha d’omplir una enquesta informativa indicant el nivell de coneixement de programació, la raó per la qual s’hi accedeix i les àrees d’interès.

En accedir-hi, es pot escollir entre:

  • Consultar els tutorials d’informació sobre el funcionament de la plataforma —el projecte anomenat Hello World—, les vídeo guies al canal de YouTube i les pàgines d’ajuda.
  • Modificar el perfil, personal o de desenvolupador. Des del perfil personal és interessant l’opció de poder afegir un currículum i marcar-se com a disponible per a ser contractat.
  • Crear un projecte. En tot moment es pot demanar ajuda clicant a “contactar amb un humà”.

Funcionalitats com a social coding

hubotAmb un compte d’usuari registrat, permet relacionar-se amb altres usuaris, gestionar, descarregar i crear repositoris, lliurar contribucions a altres repositoris i revisar canvis de codi:

  • El Branching és la manera de treballar diferents versions d’un repositori en un moment determinat: es treballa amb la versió principal —master— tal i com estava en el moment en què es va fer la còpia. Les diferents versions del master s’anomenen features, i s’entenen com a funcionalitats, components, peces. Arriba un moment en què es fusionen amb la versió master per tal d’incloure les noves funcionalitats desenvolupades en la branca.
  • Els canvis guardats s’anomenen commits, entesos com a modificacions fetes per un programador i que s’han integrat al codi. Cada commit adjunta un commit message, que conté la descripció del canvi per tal que els altres programadors que hi contribueixen entenguin què s’hi ha fet i per què.
  • Un cop guardats els canvis es poden sol·licitar revisions, pull requests, la llavor col·laborativa de GitHub. El procés consisteix en proposar als altres programadors que revisin els canvis per poder-los incorporar a la versió del master es què s’ha treballat. Els canvis, addicions, sostraccions o esmenes del contingut es ressalten en verd i vermell. Es pot demanar una revisió encara que el codi no estigui en la seva versió final.
  • Hi ha la possibilitat de puntuar un projecte atorgant estrelles, un indicador de la popularitat del projecte, més que de la qualitat.
  • S’inclou la xifra de contribucions privades al perfil.
  • L’opció explore serveix per fer una ullada al que fan altres desenvolupadors, a banda de fer codi: col·leccions d’aplicacions, articles i recursos monogràfics temàtics, llistat d’esdeveniments relacionats, etc.

Funcionalitats com a servei d’allotjament de fitxers

GitHub inclou repositoris públics i privats. Si hom no vol registrar-s’hi pot navegar pels repositoris públics, però res més. L’usuari registrat que vol mantenir el seu codi en privat ha de pagar. Alhora, GitHub també guanya diners oferint aquestes versions privades a les empreses tecnològiques. Com que no admet publicitat, els costos dels serveis que ofereix són compartits entre els usuaris privats i els inversors. Al contrari que altres serveis, els preus de GitHub no es basen en el número d’usuaris connectats, sinó en els projectes oberts. Dit d’una altra manera, en el número de repositoris privats que es vulgui mantenir. Tot i això, els plans de pagament permeten un número il·limitat de col·laboradors i de repositoris públics. Admeten comptes institucionals a banda del personals, pensats per a organitzacions que necessiten gestionar permisos per als seus treballadors.

Complements

Tot i que GitHub és utilitzat com a eina per a programar, a més de codi font també dóna suport als formats i les característiques següents:

  • Facilita la citació dels repositoris. Escollint l’opció d’arxiu del repositori a Zenodo, aquesta eina s’encarrega de l’assignació d’un DOI (Digital Object Identifier).
  • Inclou documentació: un fitxer README, el tipus de llicència que controla el repositori, el codi de conducta d’ús esperat, i les recomanacions per contribuir al projecte.
  • Wikis.
  • Petites pàgines web que allotgen el repositori públic de GitHub. El format d’URL és:
http://usuari.github.io
  • Llistes de tasques pendents —issues— dins dels arxius, consultables i executables per tercers, així com la possibilitat de fer seguiment de temes i assumptes, incloses peticions d’ajuda.
  • Arxius psd (per a control i comparació de versions anteriors).

Les condicions d’ús de GitHub no requereixen que els projectes de programari públic allotjats segueixin la definició de codi obert. Per tant, és aconsellable que els usuaris i desenvolupadors que vulguin fer ús del programari publicat a GitHub llegeixin la llicència per saber què els permet.

Altres serveis

GitHub també proporciona altres serveis, combinant les funcionalitats del social coding i el servei d’allotjament de fitxers:

  • Gist és un lloc pensat per mantenir fragments de codi. Inclou control de versions, branching i encriptació SSL (pels Gists privats). Cada Gist té el seu propi repositori Git, així que múltiples fragments de codi poden estar continguts dins d’un repositori i ser fàcilment utilitzats. A més, la versió del codi, ja sigui fork o no, es pot retornar a l’autor original en forma d’adjunt. Aquí es va crear Speaker Deck, una aplicació que converteix els fitxers pdf en presentacions de diapositives.
  • GitHub Business és similar al servei públic de GitHub, pensat perquè les grans empreses puguin desenvolupar programari i alhora mantenir-lo als seus repositoris darrera un tallafocs. Agrupa els diferents editors en GitHub Teams.
  • Organizations, comptes compartits per tal que els usuaris puguin col·laborar en projectes. L’administrador del compte gestiona l’accés dels membres a les dades i als projectes, i a un número il·limitat de repositoris en obert.
  • Marketplace, des d’on es poden descarregar aplicacions que faciliten el flux de treball de codificació, de gestió de projecte, de revisió, etc.
  • Programa Educatiu, l’anomenat Pack de Desenvolupador de Github de l’Estudiant (en anglès GitHub Student Developer Pack), per donar als estudiants accés gratuït a eines i serveis de desenvolupament populars.
  • Releases, per fer una versió lliurable del programari als usuaris. És una versió del programari prèviament comprovada (tested).

Utilitats

Revisió de canvis

Les eines socials —o híbrides, com en el cas de GitHub— han d’estar enfocades a ajudar als estudiants a convertir-se en integradors i creadors d’informació —programari en el cas de GitHub— nodrint-les de credibilitat i de qualitat. Això els permet divulgar els seus projectes amb immediatesa, tot contribuint a la diversitat informativa. Ara bé, ens hem de plantejar si les xarxes socials d’informació faciliten la participació i el debat, el desenvolupament de pensament crític, o si únicament contribueixen a l’augment de la capacitat d’influència d’uns pocs usuaris i a la repetició de codi —respostes planes, de missatge formatiu buit— donada la manca de contextualització de la informació.

En el cas de GitHub, l’eficiència d’un projecte es calcula en funció del seu creixement. També es demostra mitjançant l’habilitat dels seus desenvolupadors per treballar de manera distribuïda, col·lectiva i uniforme quan reben sol·licituds de canvis o revisions, complint aquestes sol·licituds de manera fidel.

Cal ressaltar, paradoxalment, que en un món de codi lliure i de dades en accés obert, els projectes més populars són els relacionats amb el programari dissenyat per funcionar amb els diversos productes d’Apple.*

Bibliografia