1. Introduction2. Scope&Goals3. Science&Software

i. Reproducibilityii. SoftwareQualityiii. SoftwareDevelopmentiv. SoftwareDocumentationv. Guide

4. OpenSourceBasicsi. Mindsetii. Argumentsagainstopensource...andhowtodisprovethemiii. SuccessStoriesiv. LegalStuffv. Peoplevi. Guide

5. GitHubi. Basics:Accounts&Repositoriesii. Fork&PullWorkflowiii. SocialCodingiv. GitHubforEducation

6. SoftwareCommunitiesi. CommunityBuildingandOpennessii. MarketingandPublicRelationsiii. TypesofContributorsandTasksiv. OpenSourceinYourDomain

7. ScientificPublishingofDataandSoftware8. Contribute9. Glossary

TableofContents

PublishingResearchSoftwareasOpenSourceonGitHub

2

Howcanyoupublishresearchsoftwareasopensource?Anddosowithouttoomuchoverheadandactuallygainimpactbyleveragingtheopensourceapproach?

Thesequestionsareansweredinthisbestpractice"PublishingResearchSoftwareasOpenSourceonGitHub".ItispublishedbytheGLUESproject'sSDIteam.

ThisworkislicensedunderaCreativeCommonsAttribution4.0InternationalLicense.

The"sourcecode"ofthisdocumentishostedonGitHubandthebookwaswrittenandpublishedusingGitBook.

Thetextisdesignedtobereadinthewebview,butPDFandotherformats,e.g.fore-readers,areaavailableaswell.

Version:0.1

Thankstothesepeopleforprovidingcontents,givingvaluablefeedback,reportingerrors,...

DanielNüstSimonJirkaAnnHitchcock

Wanttobecomeacontributor?Checkourcontributionguidelines.

AuthorsDanielNüst,@nuestonGitHub,d.nuest@52north.org

Introduction

LICENSE

Aboutthisbestpractice

Contributors

Contactinformation

PublishingResearchSoftwareasOpenSourceonGitHub

3Introduction

SimonJirka,s.jirka@52north.orgAnnHitchcook,a.hitchcook@52north.org

Twitter:@FiveTwoNhttps://twitter.com/fivetwon

PublishingResearchSoftwareasOpenSourceonGitHub

4Introduction

Researchtodayisdrivenbydata.Itcomesfromvarioussourcesandisofmanifoldaspects.Oftenthisdataispublishedandanalyzedas"open"dataoutofresearchprojectsrangingfromsinglethesistointernationalconsortium.Suchprojectshavealifespanof2to4years.Oftenthesoftwaredevelopedforanalysisisdeemedunfitforpublication,althoughtheideaofopensourcesoftwareiswidelyknown.Toooftenthereasonfornotpublishingthesoftwareislackoftimeorknowledge.Thisbestpracticewillprovideargumentsandworkflowsthatencourageeffectiveandcost-efficientpublication,aswellasensurelong-termmaintenanceandmanagementofresearchsoftwareasopensourcesoftware.

Thetargetaudienceisprojectmanagers,workgroupleadersandscientistsfromalldomainsthatusecodefortheirresearchbuthavenotyetpublishedit.Thedocumentprovidesanoverviewofrelevanttopicsandprovidesreferencestomoredetailedwork.Theauthorsaimtouseplainlanguagetoexplaintechnicaltopics,butalsointroducethe"lingo"ofopensourcesoftwaredevelopment.WhereusefulweaddOpenGuidestoapproachatopicfromanopinionatedstandpointtoanswerthemostrelevantquestionsforpracticalapplications.

Thegoalofthispublicationistogiveresearchprojectleaders,principalinvestigators,andresearchersasetofworkflowsthatincreasetheamountofreusableopensourcesoftwaretooptimizeresearchanditsimpact.Italsoprovidesargumentsforpublicationwhennegotiatingwithsupervisorsorfundingagencies.Pleasenotethatitisbasedonanopensourceinitiative/smallenterprise'sexperienceinfundedresearchprojects.OpenSourcesoftwareisusedwhiledoingappliedresearchinthegeoinformaticsdomain.

Wecannotcoverspecifcprogramminglanguagesorrecommendspecificlibrariesofapplicationdomains,suchashydrology,physics,orgeomorphology.Butwethinksuchrecommendationswouldbeuseful,sopleasefeelfreetocontributesuchinformationaschapterstothisdocument.

Weuseiconsinthetexttoshowwhencontentisimportant,upfordiscussion,anopinion,coverslegalaspects,especiallyrelevantforPhDstudents,basedonexternalresourcesorquotes,relatedtoscientificpublications,coversnewor"hot"topics,openfordiscussionoryourcontributionsareneeded,orwesimplyreallylikeit.

ScopeandGoals

Guide:ShouldIpublishmycode,when,andwhatpartofit?

PublishingResearchSoftwareasOpenSourceonGitHub

5Scope&Goals

Yes,publishreusableabstractcorefunctionsfromthestart.Don'tpublishyourcodeaspartofa"dissemination"for"otherstouse"attheendofyourwork.Ifyoudon'tplantocontinueworkingonsomething,don'tuseopen-sourcingtosilenceyourconscience.

Bypublishingyourcodeyoucaneffectively

demonstratescientificrigor,improvethequalityofthecodeandsubsequentlyyourresearch,startcollaborationswithotherresearchers.

Whatpartofthecodeshouldbepublished?Publishreusablepartitions/corelibraries/abstractfunctionality,insteadofthe"solution"toyourownproblem.Thisallowsotherstore-useyourcodeandcontributetoimproveit,andyoutotakeadvantageoftheirimprovements.Yourrequirementsarestillmetbythepublishedcode,eventhoughyoumightactuallyworkinaderivedspecializedproject.

Ifpossible,donotstartanewproject,butidentifyanexistingproject,frameworkorcommunityandcontributeyournewworktoit.Ifyouhaveavalidcontributionandcanmaintainitforsometime,anycommunitywillwelcomeyouwithopenarms.

Theguidesinthisbookapplybothtoverysmallprojects,suchasanewalgorithmforaspecificprobleminbiochemistry,andtolargeones,suchasanewcloud-basedcommunicationframeworkforthenextgenerationoftheinternetofthing'ssensornodes.

Thisisanopinionatedview.Whatisyourexperience?Getintouchandcontribute!</p>

Furtherresources

https://wiki.52north.org/bin/view/Documentation/BestPracticeOpenSourceForUniversityResearchers

PublishingResearchSoftwareasOpenSourceonGitHub

6Scope&Goals

Inthischapterwetrytoconnecttheworldsofscientificresearchwithopensourcesoftwaredevelopment.

HowcanIdevelopsoftwareaspartofresearch?Whatisthedifferencebetweensoftwareandscientificpapers?Whatisgoodsoftware?Whatisresearch?Howissoftwaredevelopedanddocumented?

Science&Software

PublishingResearchSoftwareasOpenSourceonGitHub

7Science&Software

Reproducibilityliesatthecoreofscience.Youshouldworryaboutit,especiallyifyouuseordevelopsoftwarewithinyourresearch.But(sadly)thisguideisnotaboutgoodscience,soWekindlyaskyoutocontributegoodresourcestothissectiontoanswerquestionssuchas

Whatisit,whydoesitmatter?Howdoesitrelatetosoftware?

Furtherresources:

MakingYourCodeCitableonGitHubhttp://researchcompendia.org/http://reproducibleresearch.net/Reproducibility,ReproducibleresearchandOpenresearchcomputingonWikipediaCRANTaskView:ReproducibleResearchSandveGK,NekrutenkoA,TaylorJ,HovigE(2013)TenSimpleRulesforReproducibleComputationalResearch.PLoSComputBiol9(10):e1003285.doi:10.1371/journal.pcbi.1003285Greatblogpost"10non-trivialthingsGitHub&friendscandoforscience"

Reproducibility

PublishingResearchSoftwareasOpenSourceonGitHub

8Reproducibility

Whatisgoodsoftware?

Youtellus.Forthesakeofthisguide,softwareisgoodsimplyifitdoesthejob.

Yes,weactuallyaddedafullchapteronSoftwarequality,justtomakeitlooklikewewouldhaveashortanswerforyou!

Ifyouworryaboutsoftwarequality,werecommendthefollowing:

Publishyoursoftwareasopensourcefromthestart-itwillmakeyoumoreawareofdocumentationandcode"beauty"(simpletipsformorebeautifulandbettercodingby52°Northdevelopers)andthusincreasethequality.UseanestablisheddocumentationframeworkFollowanestablishedsoftwaredevelopmentlifecycle.

Alongeranswercanbefoundinanyoftheseresources:

SoftwareQualityonWikipediaDavidChappell:TheThreeAspectsofSoftwareQuality:Functional,Structural,andProcess(industrywhitepaper)

Softwarequality

PublishingResearchSoftwareasOpenSourceonGitHub

9SoftwareQuality

Whetheryouworkaloneorinateam,itisworthunderstandingthesoftwaredevelopmentprocessyouapply.Knowledgeaboutsoftwaredevelopmentlifecyclescanhelporganizeyourresearchbetter!

Pleasereadaboutthesoftwaredevelopmentprocesses(about30mins.ofreading):

SoftwareDevelopmentProcessSelectingDevelopmentApproachAgileSoftwareDevelopment

Ifyouskippedthelist,thensimplyuseScrum(andreadthisorgetithere,andthis).

Ourrecommendation:Everythingbutanagileanditerativeapproachwilleventuallyfail,costalotofmoney,takealotoftimeandthereforedoesnotworkinresearch.Statewhichagileapproachyouapply,thenyouhaveacommonlanguage.

Softwaredevelopmentisanendlesslineof"collect,compare,decide".Tosuccessfullyemploythisprocess,youneedafewfeatures,allofwhichareprovidedbytheGitHubplatform:

SourcecodeversioningDocumentationplatform(wiki)IssueortasktrackingWebsite(mailinglistonlyifyoustilluseemails...)

Thereareothersourcecodeversioningsystems(e.g.Mercurial,Bazaar,SVN),butGitistherealdeal.Gowiththeflow-itmakesiteasierfornewdeveloperstojoinyourproject.

Therearemanytaskmanagementsystems.Trello,forexample,isgreatandintegratesverywellwithGitHub.DoesyourinstitutionhostJira,Trac,Redmine,orBasecamp?Goforit.

Youcanhostwebsitesanywhere.Ifyouneedablog,hostingwithGitHubispossiblebutmightnotbeyourfirstchoice.(seemarketing...)

SoftwareDevelopment

Process

CollaborativeSoftwareDevelopment

PublishingResearchSoftwareasOpenSourceonGitHub

10SoftwareDevelopment

TherearealsoalternativestoGitHub(seehttp://alternativeto.net/software/github/</a>andhttp://toppersworld.com/top-10-free-github-alternatives-for-private-repositories/),forexampleBitBucket,orR-Forge.Gowiththeflowofyourlanguage/domain.Itlowersthebarrierforcollaboration.Youcangetcommercialsupportandprivaterepositores,ordeployanOpenSourcecopyusingGitLab

Whatplatformworksbestforyou?Wouldyouliketolearnaboutdependencymanagement,buildmanagement,releasemanagement,orbugtrial?

PublishingResearchSoftwareasOpenSourceonGitHub

11SoftwareDevelopment

Documentationisextremelyimportant.Hereisourshortlistofrecommendations:

Documentfromthestartanduse"futureyou"asareference:imaginetheinformationneededtounderstandapieceofcode.Write"speaking"code,uselongvariableandfunctionnames,andfollowsoftwaredesignpatterns-itsaves80%ofdocumentation.Useadocumentationframeworkthatsuitsyourprogramminglanguage,(a)withaversionsupportand(b)thatallowsexternalcontributions.

PlaintextfileswithinthecodeR:MarkdownvignettesPython:reStructuredTextToptenreasonsGitHubisagreattoolforcreativewritersReadtheDocsGitHubpagesWikihostingservicesonWikipedia

Youshouldnotuseasoftware/codelicensefortextandimages.Thesearelicensessuitablefordocumentation:

AnyoftheCreativeCommonslicenses.Dependingonyourgoals,choseone!GNUFreeDocumentationLicense(discussedonWikipedia)

SeealsothelistsoffreeandnonfreedocumentationlicensesatGNU.

Thisisanopinionatedview.Whatisyourexperience?Getintouchandcontribute!

Documentation

Guide:WhatlicenseshouldIuseforDocumentation

PublishingResearchSoftwareasOpenSourceonGitHub

12SoftwareDocumentation

Youcangreatlyimprovethequalityofcodeandofyourresearchbyfollowingestablishedpracticesofthelanguageofyourchoicefromthestart.Spendalittlebitofeffortin(a)settingupareproducibledependencyandbuildsysteminthebeginningand(b)documentingthesoftwareallthetime.Thisisaloteasierthantryingtoadddocumentationor"overhaul"whenthecodeis"finished".Codeisneverfinished.Seeminglysimpleinformation,suchashowtosetuptheenvironment,orversionsofusedlibraries,issimplylostaftercodeisunusedforafewmonths.

Readaminimumofsoftwaredevelopmentprinciplessothatyouknowwhereyoucanfindhelp.Noneedtolearnsomethingyoucanlookup!Don'treinventthewheel,useestablishedlibraries.Useestablishedbuildanddependencymanagementsolutionsforyourlanguageofchoice.Evenifyoudon'tplantopublishyourcodeinpublicrepositories,dopackageitforthembecauseitwillenforcegoodpractices.

useMaven</a>orGradleforJavawriteanextensionpackage</a>forRandloadrequiredpackagesfromCRANwriteaPyPimodulewhenusingPythonuseGrunt</a>andBowerforJavaScript,andpackageyourcodeinanNPMmodule

Documentconstantlyuse"futureyou"withoutanypreviousknowledgeastherecipienttojudgelevelofdetailofdocumentationuseacommondocumentationsolution-seeDocumentation

Doyouknowtypicalframeworksforotherlanguagesusedinopensourcedevelopment?

Guide:Dosoftware"right"fromthestart

PublishingResearchSoftwareasOpenSourceonGitHub

13Guide

Inthischapterwetackletheverybasicsofopensourcesoftware.

Whatisopensource?Whatarelicensesforopensourcesoftware?Howdo"opensourcepeople"think?Isopensourcereallyworking?

ReadoninthesectionsaboutOpenSourceMindset,ArgumentsforOpenSource,SuccessStories,andLegalStuff.

OpenSourceBasics

PublishingResearchSoftwareasOpenSourceonGitHub

14OpenSourceBasics

Tounderstandopensourcedevelopmentonemustunderstandhowopensourcedevelopersthinkandwork.Thissectionmostlypointstoworthwhilereadingmaterialforarainyweekend(unlessotherwisenoted).

Opensourcehasastrongrelationtoscienceandresearch.Manyinstitutionsuseandcreate,butalsoresearchopensourcesoftware.ExplorethisworldusingGoogleScholarorMicrosoftAcademicSearch.See,e.g.Amazonforprintedpublications.

TheOSIdefinesopensourceassoftwarefollowingasetofcriteriathatensurefreedistribution,extendibility,andnon-discrimination.Thefullcriteriaareonlineandtheannotatedversionisahighlyrecommendedread.TheminimalexcerptofthedefinitionbytheFreeSoftwareFoundation(FSF)isasfollows.

“Freesoftware”meanssoftwarethatrespectsusers'freedomandcommunity.Roughly,itmeansthattheusershavethefreedomtorun,copy,distribute,study,changeandimprovethesoftware.Thus,“freesoftware”isamatterofliberty,notprice.(source)

ReadthefulldefinitionandmakeupyourownmindabouttheFSF"campaign".Isnonfreesoftwarereally"unethical"?HowdoFSFandOSIrelatetoeachother?Youcanfindanoptionalreadaboutthecontroversydefiningwhatopensourcesoftwareishereandhere.

Thereareplentyofonlinedescriptionsofthehistoryofopensource.Werecommendthefollowingpages(roughly1hourofreading):

"Historyoffreesoftware"onWikipedia"Open-sourcemovement"onWikipedia"HistoryoftheOSI""The9mostimportanteventsinOpenSourcehistory",includingacommentthreadshowingthatboilingdownopensourceto"Xevents"isimpossible.

Mindset

WhatisOpenSource?

Definition

History

Terms"free","libre"and"opensource"

PublishingResearchSoftwareasOpenSourceonGitHub

15Mindset

Freesoftwareisamatterofliberty,notprice.Tounderstandtheconcept,youshouldthinkoffreeasinfreespeech,notasinfreebeer.RichardStallmann

"Freesoftware","libresoftware"and"opensourcesoftware"haveslightlydifferentmeanings.Thesedistinctionsareimportantforthehistoryandunderstandingof"somehowpubliclyavailablesoftware".

Wikipediahasasummaryofthenaming,funquotesabouttheunfortunateacronymFLOSS,aswellasawholepagediscussingtheambiguityof"free".

Whenwesayopensourcesoftware,wemean"freeandlibreopensourcesoftware".WemightusetheacronymFOSS,buttrustyoutounderstandtheambiguityoftheEnglishword"free".

Extendedreading:

FreeasinFreedom(2.0):RichardStallmannandtheFreeSoftwareRevolutionbySamWilliams(book'sWikipediapage,208pagesplusappendix!)

Theterm"hacking"or"hackers",i.e.peoplewhohack,ispartofmainstreamculturetoday.Inopensourcecommunities,theterm"hacking"hasdiversemeanings,someofthemverypositive.Thesameskillsetisrequiredfor"cracking"illegalyintosecuresystemsandforsolvingaveryhardinformaticsproblemcreatively.Sodon'tworryifsomeonetalksabouta"goodhack"!

Forafullhistoryofthetermandrelatedconceptssuchas"white/blackhat","cracking",or"hackerethic",seeAppendixAofFreeasinFreedom(2.0):RichardStallmannandtheFreeSoftwareRevolutionand,asalways,Wikipediaon"Hacker"oron"Hackerspace"(a.k.ahacklab,hackspaceormakerspace).

Toalargeextent,opensourcedevelopersarenodifferentfromanyothersoftwaredevelopers.Amustreadforunderstandingthe"softwareworld"(notonlyopensource)andthepeoplelivingandworkinginit,is"WhatisCode?"byPaulFordforBloombergBusinessweek.JoshTyrangiel'sintroductionstates:

Softwarehasbeenaroundsincethe1940s.Whichmeansthatpeoplehavebeenfakingtheirwaythroughmeetingsaboutsoftware,andthecodethatbuildsit,forgenerations.

Hacking

WhatisCode?

PublishingResearchSoftwareasOpenSourceonGitHub

16Mindset

[...]asinglestorydevotedtodemystifyingcodeandthecultureofthepeoplewhomakeit.

Whilethisbookisconcernedwithsoftware,(a)"Opensource"alsoexistswithoutsoftware,and(b)ifyourresearchinvolvescreationofhardwareaswell,there'sawholeotherworldoutthere!

Extendedreading:

"Opensource"onWikipedia(withoutsoftware)HistoryofOpenSourceHardwareattheOpenSourceHardwareAssociation

Getintothecultureofsoftwaredevelopersandopensourceenthusiastsandtryanycombinationofthefollowing.

RegularlyreadXKCD,Whatif?,DilbertandGeek&Pokewebcomicssoyoucanmakeconversationatlunch.FollowtechnologynewsonSlashdotorArsTechnica.WatchThisWeekinTech.Ifyou'reinGermany,heiseonlineisalsogoodtofollowfortechnologynews.

OpenSouce(Hardware)

Theextramile

PublishingResearchSoftwareasOpenSourceonGitHub

17Mindset

Inmostcases,theoppositeistrue.Severalfactorsmayevenensureabettersupportforopensourcecomponentsthanforclosedsourcesoftware.Formanyopensourcesoftwareprojects,thereisalargedevelopercommunityavailable.CommunicationtakesplaceviatheWeb,mailinglists,etc.Hereyoucangetdirect,first-handsupportfromthedevelopersofthecode.Sincemostcommunicationisextremelytransparent,youcanevaluateinadvancehowthesedifferentsupportchannelsworkwhendecidingwhichopensourcesoftwarepackagetouse.

Manyopensourceprojectsarebackedbycommercialcompanies.Thesecompaniesofferprofessionalsupportservicesforspecificopensourcepackages.Furthermore,youarenotboundtoonesinglevendor(seevendorlock-in)forthesesupportservices.Sincethesourcecodeisopen,anyonecandevelopfixesorenhancements.However,ifyourelyonproprietarysoftwareandthevendordiscontinuestheproduct,goesoutofbusiness,orifthesupportcontractsofferedbythevendorbecomeunattractive,youmayrunintoaproblem.

Anopensourcelicenserequiresthesourcecodetobepublished,however,therearemanywaystosellitsuccessfully.Inmanycases,customersneednotonlythesoftware,butalsoapackageofrelatedmaterialsandservices.Thus,anattractiveofferincludingspecificsupportagreements,enhanceddocumentation,helpforinstalling/integratingthesoftware,training,etc.wouldmakesense.OpenSourceSoftwaredoesnotmean“non-commerical”!

’Freesoftware’doesnotmean‘noncommercial’.Afreeprogrammustbeavailableforcommercialuse,commercialdevelopment,andcommercialdistribution.Commercialdevelopmentoffreesoftwareisnolongerunusual;suchfreecommercialsoftwareisveryimportant.Youmayhavepaidmoneytogetcopiesoffreesoftware,oryoumayhaveobtainedcopiesatnocharge.Butregardlessofhowyougotyourcopies,youalwayshavethefreedomtocopyandchangethesoftware,eventosellcopies(source).

ArgumentsagainstOpenSource...andHowtodisprovethem

NoProfessionalcanhelpMeifIhaveProblems

OpenSourceSoftwaremeansIcannotsellit

PublishingResearchSoftwareasOpenSourceonGitHub

18Argumentsagainstopensource...andhowtodisprovethem

WhileitmightbetruethatLinuxrequiresmoretimetocustomizeitaccordingtoyourneeds,itisnottruethatthistimeiswasted.Infact,Linux,asdomanyotheropensourcesoftwarepackages,providesalotmoreflexibilityinsettingupsystemstofityourneedsexactly.Itmighttakemoretimeinitially,butyouwillhaveasystemwhichallowsyoutoworkextremelyefficientlyintheend.

Wefocusonpublishingresearchoutputsasopensourcesoftware.Whenwetalkaboutresearch,thefocusisnotonmoney,butonmakingtheresearchcommunityawareofyourwork,showcasingyourresults,andprovidingabasisthatcanbere-usedandadvancedbyfutureresearch.Thereare,however,manywaystomakemoneywithopensourcesoftware.Thefollowingparagraphsintroducetwopossibleopensourcebusinessmodels.

TheOpenSourceGeospatialFoundationprovidesacompactsummaryaboutcommercialservicesforopensourcesoftware.Theinformationonthispageisprettysimilartotherevenueopportunitiesfollowedbyvendorsofproprietarysoftware,exceptthattherearenolicensefeesforthesoftware.Typicalelementsofsuchanopensourcebusinessmodelmaycompriseconsulting,customdevelopments(e.g.newormodifiedfeatures)basedonanopensourcesoftwarepackage,maintenance,supportwithspecificservicelevels,training,etc.Opensourcesoftwaremayhelpresearcherssuccessfullysubmitnewresearchanddevelopmentprojectproposalstofurtheradvanceandimprovetheirsoftware.

Wikipediaalsohasacomprehensivearticleondifferentapproachesforopensourcebusinessmodels.

Forexample:

Dual-licensing:Publishyoursoftwareunderanopensourcelicense,butforthoseuserswhocan'tcomplywiththislicense,sellcommerciallicenses.Softwareasaservice:Sellyoursoftwareasaservice(e.g.byprovidingaccesstoyoursoftwareasacloudservice).Proprietary/OpenSourcecombination:Combineyouropensourcesoftwarewithproprietarysoftwarethatyoumightsell(e.g.proprietaryextensions).Othersourcesofrevenuemaycomprisethesaleofbrandedmerchandise,voluntarydonations,partnershipswithfundingorganizations,open-sourcebounties,advertising-supportedsoftware,orcrowdfunding.

"LinuxisonlyforfreeifyourTimehasnoValue"(source)

YoucannotearnMoneywithOpenSource

PublishingResearchSoftwareasOpenSourceonGitHub

19Argumentsagainstopensource...andhowtodisprovethem

Therearemanyotheropportunitiestomakemoneyfromopensourcesoftware.Shareyourexperience.

Softwarepatentingisahighlycontroversialtopic.Dependingonthecountryinwhichyoulive/work,itmightnotevenbepossibletopatentyoursoftware.

Animportantfactorintoday'ssciencecommunityistomaximizetheimpactofyourresearch.Thisiswhymanyfundingagenciesstartrequiringpublicationstobeopenaccessandsoftwaretobeopensource.Theideaofpatentingcodeiscompletelycontrarytotheserequirementsandtheprinciplesofopenandreproduciblescience.

RecommededreadingonsoftwarepatentsshouldstartwithWikipediaarticle.

IcannotpatentmyCode

PublishingResearchSoftwareasOpenSourceonGitHub

20Argumentsagainstopensource...andhowtodisprovethem

Opensourcesoftwareisnotanicheproduct.Infact,thisverybookisaproductcreatedwithopensourcesoftware,suchasGitforcollaborationandversionmanagement,FirefoxforeditingandmostlikelyApacheornginxonaLinuxwebserverforcontentdelivery.

Therearemanysuccessstoriesintheopensourceworld.Hereareafewexamples:

ApacheSoftwareFoundation:TheApacheSoftwareFoundationisresponsiblefortheApachesoftwareprojects.Oneofthemost-wellknownApacheprojectsistheApacheHTTPServer,theworld'smostwidelyusedwebserversoftware.TherelevanceoftheApacheprojectsbecomesapparentifyoulookatthecompaniessupportingtheApacheSoftwareFoundation(e.g.Google,Microsoft,IBM,Yahoo).LibreOffice:ThisisanopensourceofficesuitepublishedandmaintainedbyTheDocumentFoundation.ItisbasedonOpenOffice.org,fromwhichitwasforkedin2010,whichwasoriginallyanopen-sourcedversionofStarOffice.LibreOfficeenjoysquitealargeusercommunityandisacommonalternativetoproprietaryproducts.Linux:Linuxisoneofthemostprominentexamplesofopensourceprojects.Fromitsfirstreleasein1991,ithasbecomeawidelyusedoperatingsystem.PopularplatformssuchasAndroidrelyontheLinuxkernel.Webbrowsers:Twoofthemostpopularprojectsrelyonopensourcelicenses.MozillaFirefoxisavailableundertheMozillaPublicLicense.TheChromebrowserpublishedbyGoogleisdistributedasfreeware,however,significantpartsofitssourcecodeareavailableasaprojectcalledChromiumundertheBSDlicense.

Inthegeospatialcommunity,twoprojectsforofferingmapservicescontributeto/publishopensourcesoftwareandarethebasisforasoftwareasaservicebusinessmodelaswell.

CartoDBoffersservicestocreateandhostmapsontheWebasafreemiumservice.However,interestedusersmayaccesstheplatformimplementationasanopensourcepackagetoinstalltheirowninstanceortomodifyit.MapBoxofferssimilarservicestoCartoDB's.Significantmodulesofthisplatformhavebeenpublishedasopensourcesoftware.Furthermore,MapBoxhascontributedtomanyotheropensourceprojects.

Differentorganizationsneedingacertainfunctionalitycanteam-uptofundthenecessarydevelopments.Anexamplehereofisthe52°NorthSensorObservationService(SOS)implementation.ThisWebserviceallowsuserstopublishmeasurementdata/sensordataontheWebthroughastandardizedinterface.Severalpartnersand(research)projectscontributedeitherfundingfor52°Northdevelopersorcodetodevelopthiscomponent.Due

SuccessStories

PublishingResearchSoftwareasOpenSourceonGitHub

21SuccessStories

torecentlegalobligations,variousEuropeancountriesneedatooltoreporttheirairqualitymeasurementsinastandardizedformattotheEuropeanEnvironmentAgency(EEA).Togetthenecessary52°NorthSOSenhancements,severalcountries(i.e.Belgium,TheNetherlands,SwedenandtheUnitedKingdom)haveteameduptofundthedevelopment(seealsoStreamliningEuropeanairqualitydatareportingandexchangeviaSOS4.3).Thisisanexcellentexampleofhowdifferentstakeholderscanjoinforcestoadvanceopensourcesoftware.

OpenHuboffersavarietyofmetricstoassessopensourceprojects:theirpopularity,activities,etc.

Overviewsofsuccessfulopensourceprojectsareavailable:

http://www.itworld.com/article/2827587/enterprise-software/10-most-successful-open-source-projects-of-2012.htmlhttp://www.techdrivein.com/2010/08/11-biggest-open-source-success-stories.htmlhttp://royal.pingdom.com/2009/05/29/the-8-most-successful-open-source-products-ever/

PublishingResearchSoftwareasOpenSourceonGitHub

22SuccessStories

"IANAL"-Iamnotalawyer.Wehavesomeexperiencewithopensourceslicensing,butwecannotgiveyoutheprofessionaladvicethatyourrequire.Therearemanydifferentlegalsystemsintheworld.Ifyouareindoubtaboutlegalmattersregardingyouropensourcesoftwareorsoftwarethatyouuse,thengetalawyerorgetintouchwithcolleaguesandyourlegaldepartment.

Thereis,however,aplethoraofguidesandopinionsavailableonlineandinbooks.Inthissection,weintroducesomebasicinformationandtrytosummarizethematterforthemosttypicalscenarios.

©

Copyrightisalegalconceptthatgivesthecreatorofaworkcertainrightsto(exclusively)usethatwork,grantpermissionstootherpersons,etc.Itisintendedtoprotectthecreator(s)fromeconomicalandideologicalabuseoftheirworks.You,asacreator,havethecopyrightbydefaultandusuallyyoucandetermineunderwhichconditionsyourworkmaybeusedbyothers.However,theexactscopedependsonthespecificapplicablelaw(e.g.thecopyrightlawsofspecificcountries).

Pleasenotethattherearealsolimitationsregardingthecopyright,whichgrantsomeexceptionsforspecificcases.Thisisreferredtoas“fairuse”.WerecommendreadingthisWikipediaarticle.Otherlimitationsconcernthecopyright'sexpirationaftercertainperiods(dependingonthespecificlaws).

Copyrightrequiresthattheworkyoucreatedhasacertainthresholdoforiginality.Thisthresholdisgenerallyratherlow.Aninterestingdiscussionaboutthistopiccanbefoundhere.

History:IntheoldRomanEmpireandthemedievalages,therewasnocopyright.Atthattime,itwasextremelylaborioustocopyatext,sothiswasnotreallyanissue.However,thischangedwiththeinventionoftheletterpressandledtothe“Printer’sPrivilige”Actof1709,alsoknownastheStatuteofAnne(Britishlaw).OtherexamplesincludetheDroitd’auteur(France,1793:authorswantedacknowledgmentnotmoney)ortheGerman

LegalStuff

Basics

Copyright

PublishingResearchSoftwareasOpenSourceonGitHub

23LegalStuff

Urheberrechtsgesetz(UrhG)from1965.

Ifyourworkisfree,youmightalsowantthatanymodificationorextensionsofthisworkbefree.Thisconceptiscalled“copyleft”.Copyleftensuresthatyoursoftwareisfreeandthatallmodificationsandextensionsofyourcodehavetobefreetoo.GNUexplainsthisasfollows:

"Proprietarysoftwaredevelopersusecopyrighttotakeawaytheusers'freedom;weusecopyrighttoguaranteetheirfreedom.That'swhywereversethename,changing'copyright'into'copyleft.'”

Wedistinguishbetweendifferenttypesofcopyleft.Generally,therearethreemaincategories:

StrongcopyleftrequiresallderivedworktoinherittheoriginalcopyleftlicenseWeakcopyleftreferstolicenses,whichdonotrequirethatallderivedworkinheritthecopyleftlicense.Forexample,youmaylinkyoursoftwaretoaweakcopyleftlicensedlibrarywithoutusingthesamelicense.However,ifyouchangetheoriginalsoftware,thecopyleftlicenseneedstobekept.Thisisuseful,forexample,ifyouwanttopublishlibrariesthatshouldbere-usablebyabroadrangeofotherprojects.Non-copyleftdoesnothaverequirementsonthelicenseofderivedsoftware.

Asyouwillseelateron,thedifferenttypesofcopyleftareanimportantfactorwhenchoosinganopensourcelicenseforyoursoftware.

Recommendedreading:

http://www.gnu.org/copyleft/http://en.wikipedia.org/wiki/Copylefthttp://www.visionmobile.com/blog/2011/03/theopen-source-trials-hanging-in-the-legal-balance-of-copyright-and-copyleft/

Internationalconventionsregulatehowtohandlecopyrightbetweendifferentcountries.AnimportantelementistheBerneconvention.

Copyleft

GlobalTradeAgreements

SoftwareCopyrightandCopyrightInfringement

PublishingResearchSoftwareasOpenSourceonGitHub

24LegalStuff

Allsoftware,proprietaryandfreeandopensource,reliesoncopyright.Althoughcopyrightinandofitselfhasalonghistory,itsapplicationtothespecificsofsoftwareisstillinthemaking.IntheEUandUSA,thereismainlyCaseLawonthistopic.Theconceptofcopyrightlaysthefoundationfortheconditionsofopensourcelicenses.

RecommendedReading:

SoftwareCopyright

CopyrightInfringement

Ifyouareusingcopyrightedworkswithoutpermissionfromthecopyrightholder,orifyoudonotfollowtheirtermsandconditions,thisiscalledcopyrightinfringement.Thiscouldhaveseriouslegalconsequences.Inordertoavoidcopyrightinfringements,youshouldconsiderseveralaspects:

Whenyouuseopensourcecode,lookfortwotypesoflegalinformation1)thelicense(s)ofthecodeand2)thecopyrightnoticesofcontributingauthors(seealsoManagingCopyrightInformation).

Makesureyouunderstandthecompatibilityofthelicense(s)ofthiscodewiththelicenseyouareusingforyourowncode(andwiththelicensesofothercomponentsyouareusing).

Whenyoupublishyourcodeunderanopensourcelicense,youarerequirednotonlytoprovideinformationaboutthelicenseyouareusingyourself,butalsoaboutthelicensesofalllibraries/softwarethatyouareusinginyoursourcecode.Thereareefficienttoolsandmechanismsthathelpyoutracecontributionsandlicensesofanythirdpartycodeinmanydistributedversioncontrolsystems.

Inadditiontothecopyleftlicenses"strongcopyleft","weakcopyleft"and"non-copyleft"mentionedabove,thereisaspecificcategoryknownas"publicdomain”.Thiscoversworksforwhichtheintellectualpropertyrightshaveexpiredorhavebeenforfeited.Othertypesoflicenses,suchasCreativeCommons,arenotreallyintendedforsoftware.Theydonotcontainanyprovisionsforthedistributionofsourcecode.ItisNOTrecommendedtouseCreativeCommonslicensesforsoftware.

LicenseTypes

PopularLicenses

PublishingResearchSoftwareasOpenSourceonGitHub

25LegalStuff

Opensourceprojectstendtofavorcertainlicensesoverothers.Thefollowingoverviewshowssomeofthemostcommonlyusedopensourcesoftwarelicenses:

MITLicense(MIT)andBSDNon-copyleftlicensesVerypermissivehttp://en.wikipedia.org/wiki/MIT_Licenseandhttp://en.wikipedia.org/wiki/BSD_licenses

ApacheSoftwareLicense(ASL)Non-copyleftPermissivehttp://www.apache.org/

GNUGeneralPublicLicense(GPL)Strongcopylefthttp://www.gnu.org/licenses/

GNULesserGeneralPublicLicense(LGPL)Weakcopylefthttp://en.wikipedia.org/wiki/LGPLhttp://www.gnu.org/licenses/

AfferoGeneralPublicLicense(AGPL)StrongcopyleftClosesaloopholethatmainlyappliestosoftwaredeployedonWebservers(seehttp://www.gnu.org/licenses/why-affero-gpl.en.html)http://www.gnu.org/licenses/

Seeexplanationsofthedifferentlicensesforsoftwarecode.

Othertypesoflicenses,wouldbebettersuitedforworksotherthansoftwarecode.

Creativeworkorart:LicensessuchasCreativeCommonsOpendata:LicensessuchasOpenDataCommons(ODC)Openhardware:Manyprojectsuselicensesinspiredbyopensourcesoftwarelicensesbutwithimportantdifferences(seealsoOpenSourceHardware).

Ifyouwanttocontributetoanopensourceproject,youareoftenrequiredtosignaso-calledcontributorlicenseagreement(CLA).ThesignedCLAenablesthelegalbodybehindanopensourceproject

toworkwithyourcodecontribution(e.g.toreproduce,tomodify,tocreatederivative

ContributorLicenseAgreements

PublishingResearchSoftwareasOpenSourceonGitHub

26LegalStuff

worksandtocombinethecontributionwithothersoftwarecode)togranttheOpenSourceLicensetopotentialuserstochangethetermsoftheOpenSourceLicenseforaparticularsoftwareprojectifnecessary(e.g.changingfromastrongcopyleftlicensetoaweakcopyleftlicense)tohandlelegaldisputes.

TheCLAdoesNOTrequireyoutotransferthefullintellectualpropertyrights(IRP)associatedwithyourcopyright(insomecountriesthisislegallyimpossibleand,fromacompanyviewpoint,itisoftenundesirable).Instead,youtransferonlythoserightsnecessarytoallowthelong-termlicensemanagementoftheprojecttowhichyouarecontributing.ThefollowingexampleofCLAsgiveyouanimpressionofhowtheywork:

Apache:http://www.apache.org/licenses/#clas52°North:http://52north.org/about/licensing/contributors-licenseagreement-faq

Recommendedreadings:

http://www.oss-watch.ac.uk/resources/clahttp://en.wikipedia.org/wiki/Contributor_License_Agreementhttp://development.contributoragreements.org/https://wiki.eclipse.org/CLA

Copyrightnoticesandlicenseheadersarenotrequiredtosecurecopyright.Basedonmostnationallaws,thecreatorofaworkautomaticallyholdsthecopyrightthemomenttheworkiscreated(e.g.ifyouhavewrittenalineofcode).However,thisdoesNOTmeanthatyoushouldnotprovidecopyrightnoticesandlicenseheadersastheyhavecertainlegalimplications.

Ifsomeoneinfringesyourcopyrightandtherearenocopyrightnotices/licenseheaders,hemightusethisasanargumenttoreduceyourclaims.Thelicenseheadermakesiteasytoimmediatelydeterminetheauthorandlicenseofacertainpieceofsourcecode.Youimproveyourvisibilityastheauthorofacertainpieceofsourcecode.

Youcanfindmoreinformationonthistopichere.

Manyopensourceprojects(e.g.Eclipse,Apache)relyontrademarkingtomaintaincontrol

NoticesandLicenseHeaders

Trademarking

PublishingResearchSoftwareasOpenSourceonGitHub

27LegalStuff

ofaproject'sidentity.Youcancontrolbetterwhoisusingyourlogoornameandinwhatcontextifyouhaveregisteredcorrespondingtrademarks.Asyoucanimagine,thiscanbecomeaseriousissue.

RecommendedReading:

http://communityovercode.com/2011/01/trademarks-in-open-source/http://www.ifosslr.org/ifosslr/article/view/11

TheUK-basedorganizationOSSwatchisagreatresourceaddressingmanyaspectsofthischapter:http://oss-watch.ac.uk/resources/ipr

FurtherResources

PublishingResearchSoftwareasOpenSourceonGitHub

28LegalStuff

Inthissectionwebrieflylistsomepeopleyoushouldhaveheardaboutfromtheworldofopensourceandfreesoftware.

FSFFounderFreesoftwareactivistIn1983hewrotethe"GNUisnotLinux"a.k.a.theGNUManifestoCoinedtheterm"Freeasinspeechvs.freeasinbeer"More:https://de.wikipedia.org/wiki/Richard_Stallman

FounderofOSIWrotethesenotableessays-worthreading!

"TheCathedralandtheBazaar""HomesteadingtheNoosphere"

More:http://en.wikipedia.org/wiki/Eric_S._Raymond

"Inventor"ofLinuxandgitMore:https://en.wikipedia.org/wiki/Linus_Torvalds

ProfessoratHarvardLawSchoolandpoliticalactivistCofounderofCreativeCommonsMore:https://en.wikipedia.org/wiki/Lawrence_Lessig

People

RichardStallman

EricS.Raymond

LinusTorvalds

LawrenceLessig

PublishingResearchSoftwareasOpenSourceonGitHub

29People

Yourealizehavingnolicensedoesnotmakeyourprojectusablebyothers.Ifnot,pleasereadtheentryabout"Nolicense"intheFSFlicenselistandthisstudyaboutlicensesonGitHub.

Therearesomanychoicesoutthereandtheopensourcelicenseworldiscomplex.Westronglyrecommendtogowithoneofthemostusedandestablishedlicenses.ThesearedividedintothreebroadcategoriesandbrieflyexplainedbyGitHubfolksatchoosealicense.com.Theydon'tsuggestanylicenseinparcticularandevenexplainthe"nolicense"option.Choosingalicenseisnowatwo-minute-task.

Basedonourexperience,werecommendtheApacheLicense.Itisclosertotherealworld,ascomparedtothe"short"licenses(MIT,BSD).Ittakesintoconsiderationthattherealworldisabadplacewithsoftwarepatents,butalsoallowsanycommercialapplicationtointegrateandextendasoftwareproject.Yourownideas,third-partylibraries,i.e.softwarethatyouuseorextend,haveanimportantimpactonchoosingalicense.

Theminimumnumberofstepsrequiredforchoosingalicenseforsoftwareresultingfromaresearchprojectareasfollows.

1. Createacomprehensivelistofyour"third-partylicenses"-softwarethatyoustrictlyrelyonordirectlyextendandtheirlicenses.

2. Gotochoosealicense.comandpickalicensethatfitsyourgoals.3. Checkallthird-partylicensesforcompatibilitywithyourchosenlicense.

Thisrequireswebsearchesandpotentialinvolvementofalawyerspecializinginopensourceifthedependencies'licensesarenottypicalones.Sadly,weareNOTlawyersandcanNOTmakeclearrecommendationshere.Checkthefollowingwebsites,butjudgeforyourselfiftherecommendationsapplytoyou.In90%ofthecases,theanswerisstraightforward,butduediligenceisrequired.

"Comparisonoffreeandopen-sourcesoftwarelicenses"onWikipediaOSSWATCHlicencedifferentiator

52°North'slistofthird-partycomponents

4. MakesureALLsoftwarecontributorsareokwiththechosenlicense.5. Checkwithguidelinesoragreementsaccompanyingthefundingforyourdevelopment,

e.g.researchgrants.6. Reviseyourdecisionifanyof3.to5.resultinissues.Ifchoosealicense.comisnot

detailedenough,answersevenquestionsintheOSSWATCHlicencedifferentiator.

Guide:WhatlicenseshouldIuseformysoftwareproject?

PublishingResearchSoftwareasOpenSourceonGitHub

30Guide

7. Done.

Formoreextensivelistsofopensourcelicenses,pleaseseethelistofOSI-approvedlicensesandthelicenselistbytheFSF.ThelatteralsohasveryshortsummariesandrecommendationsforlaypeopleyetfocusesontheFSF'sperspective.

PublishingResearchSoftwareasOpenSourceonGitHub

31Guide

GitHubistheplatformforopensourcesoftwaredevelopment.Millionsofprojectsuseit(cf.GitHut).Itssuccesscomesfromitsgreatcollaborationworkflow,whichallowsdevelopers,documentersanduserstobuildsomethingtogether.GitHubenablestheideaofsocialcoding,asoftwarethatisdevelopedeffectivelybyadistributedvirtualcommunity.

GitHubprovidesextensivehighqualityonlinedocumentation:https://help.github.com/.Thus,wegiveyouabriefoverviewanddescribeouropinionofwhyGitHubsimply"works".WealsolinktotherelevantcontentsoftheexcellentGitHubBootcamp.

PublishingResearchSoftwareasOpenSourceonGitHub

32GitHub

GitHubisafreeplatformforcodeandtaskmanagement.Atthecore,itisbasedonanopensourceversioncontrolsystem(VCS)calledGit.

Therearemanytutorialstohelpyougetstarted(GettingStartedGitBasics).

Ifyoudonotliketoworkwiththecommandline,or-godforbid-youarenotworkingonLinux,installGit(availableforalloperatingsystems)andaGituserinterface.

WestronglyrecommendtostartwithGitatthecommandline.VeryexperiencedandintenseGitusersdonotuseanUI!ItwillhelpunderstandhowGitworksifyoutypecommandsinsteadofclickingfancybuttons.

Signup-https://github.com/join-togetanaccount.Createyourfirstrepository-somethinglikeaprojectbasefolder-withasingleclickandyouarereadytogo.Or,forkarepository,i.e.makeacopyofanexistingrepository,andmakethecopyyourown.Thiswayyourworkwon'taffecttheoriginalproject.

Bootcamparticles:

SetupGitForkaRepoGoodResourcesforLearningGitandGitHub

Basics:Git,Accounts&Repositories

PublishingResearchSoftwareasOpenSourceonGitHub

33Basics:Accounts&Repositories

Evenwhenyouworkwithonlytwopeople,wehighlyrecommendthe"Fork&Pull"developmentmodel.FromtheGitHubhelponpullrequests:

Thefork&pullmodelletsanyoneforkanexistingrepositoryandpushchangestotheirpersonalforkwithoutrequiringaccessbegrantedtothesourcerepository.Thechangesmustthenbepulledintothesourcerepositorybytheprojectmaintainer.Thismodelreducestheamountoffrictionfornewcontributorsandispopularwithopensourceprojectsbecauseitallowspeopletoworkindependentlywithoutupfrontcoordination.

Theadvantagesarealsotrueforprojectswithclosecollaboration,i.e.wherethereisalotofupfrontcoordination,maybeevenwithinthesameofficespace:

Everybodycandowhattheywantwithintheirfork.Changestothemainrepocanbediscussedandreviewedwithinthepullrequests.Accesscontroltothemainrepositoryarewiththeprojectmaintainer.Pullrequestsworkbetweenanyoftheforks.

Bootcamparticles:

ForkaRepo

Furtherreading:

GitHubGlossaryUsingpullrequests

Fork&PullWorkflow

PublishingResearchSoftwareasOpenSourceonGitHub

34Fork&PullWorkflow

GitHubissosuccessfulbecause,itmakescollaborationwithotherseasy.Successfulcollaborationbetweenpeoplemakes(software)projectsthemselvesasuccess.

Codeisaboutthepeoplewritingit.Wefocusonloweringthebarriersofcollaborationbybuildingpowerfulfeaturesintoourproductsthatmakeiteasiertocontribute.Thetoolswecreatehelpindividualsandcompanies,publicandprivate,towritebettercode,faster.

TheGitHuboldmissionstatement

ChrisWanstrath,oneoftheGitHubfounders,gaveagreattalk(60min.)attheEsriUserConference2014aboutGitHubandopensourceingeneral.Recommendedwatch.

Afterviewingthevideo,"watch"acoupleofrepositoriesand"follow"somepeopletostayupdated.Exploreusersprofilestoseewhatpeopleareworkingonandconnectwiththosewhousesimilarsoftwareordoworkrelatedtoyourown.

Bootcamparticles:

Besocial

Furtherreadingonsocialcoding:

Socialcoding--thenextwaveindevelopment(TechRepublic)EclipsewikiandFAQ

SocialCoding

PublishingResearchSoftwareasOpenSourceonGitHub

35SocialCoding

Yes!Seeitasabackupsolution,butGitimprovesyourworkflow,itencouragesyoutowanderoffwithnewideas(branches),switchbetweenthem,andevenmergethem.AndGitHubissimplyagreatGituserinterface.FriendsandcolleaguescanfollowyourworkonGitHubandbecomecollaborators.

WithGit(oranyVCS),youworkinplaintextfilesandkeepcodeanddocumentationcloselytogether.Thisensuresthatanybodycanunderstandwhatisgoingoninoneweek,onemonth,oroneyear.

IfIworkonmyown,doIstillneedGitHub?

PublishingResearchSoftwareasOpenSourceonGitHub

36SocialCoding

GitHubofferseducationalinstitutestheopportunitytorunclassesonGitHuborputaPhDinaprivaterepositorybeforepublishingtheaccompanyingpaper!

TwobasicaspectsareexplainedindetailontheGitHubEducationlandingpage:

Educators:Youcanteachmoreeffectivelybyhavingaplatformtocollectassignments,distributestartercodeanddiscussissueswithstudents"within"theircode.YoucantakeadvantageofthefreeOrganizationaccountsforyourclassesorgetintouchwithGitHubtorequestdiscounts.

Students:Youwillstaybetterorganizedandwon'tlooseyourwork.Youwillalsobuildaportfoliothatdisplaysyourskillsonceyoustartlookingforajob.Thereismore:theStudentDeveloperPackgivesyoufreeaccesstodevelopertoolsandinfrastructure,suchascloudhostingordomains,foralimitedtimeoraslongasyouareeligible.

GitHubforEducation

PublishingResearchSoftwareasOpenSourceonGitHub

37GitHubforEducation

Inthischapterwetacklethehumansideofopensourceprojects.

Howcanyoubuildacommunitythatlasts?Howcanyouorganizeaprojectthatservesdifferentneeds,schedulesandpeople?Howcanyoushowwhatyourprojectcando?Howcanyougethelptotakeyourprojecttothenextlevel?

Thissectionisworkinprogress.

Wehavesectionsinthemakingaboutcommunitybuilding,openness,aswellasmarketingandpublicrelations.

SoftwareCommunities

PublishingResearchSoftwareasOpenSourceonGitHub

38SoftwareCommunities

PublishingResearchSoftwareasOpenSourceonGitHub

39CommunityBuildingandOpenness

AsZachHolmanputsit,"OpenSourcedoesn'tjustmarketitself".Communicationandinteractionwiththepublicandotherdevelopersisimportanttohelpthecommunitygrowandmakeyourhardworkknowntotheworld!

Thefollowingquickreadsprovideanideaofwhatisimportantifyouwantyoursoftware/projecttobeused:

OpenSourceDoesn'tJustMarketItself(ZachHolman)Marketingopensourceismadeforgeeks(SandroGroganz)Open-SourceProjectsNeedMoreThanGoodCode—TheyNeedMarketing(MattAsay)

WeparticularlyliketheemphasisZachHolmanputsonthevalueofgreatdocumentationasmarketing!

Thefastestwaytodisseminateinformationistomakeuseofsocialmedia.Therearelotsofdifferentplatforms,butusuallythereisn'tasocialmediaexpertonhandtojugglethem.Twoimportantbut"managable"meansarebloggingandtwittering.

"Youhavesomethingtosay,andblogsprovideaplacetosayitandbeheard."(source)

Ablogismoreinformalthanapressrelease.Itis"...adiscussionorinformationalsitepublishedontheWorldWideWebandconsistingofdiscreteentries("posts")typicallydisplayedinreversechronologicalorder(themostrecentpostappearsfirst)."(source)

Ifyouarenotawareoftheconceptofblogging,thesehelpfullinksprovidebackgroundinformation:

http://weblogs.about.com/od/startingablog/p/WhatIsABlog.htmhttp://codex.wordpress.org/Introduction_to_Blogginghttp://weblogs.about.com/od/startingablog/tp/Top-Ten-Reasons-to-Blog.htm

Howtostartblogging?

http://www.wikihow.com/Start-a-Bloghttp://startbloggingonline.com/

MarketingandPublicRelations

SocialMediaisthewaytogo

Theblog

PublishingResearchSoftwareasOpenSourceonGitHub

40MarketingandPublicRelations

http://howtomakemyblog.com/10-elements-of-style-of-blog-post-writing/

Whichbloggingplatformisbestforme?

http://thenextweb.com/apps/2013/08/16/best-blogging-services/Wordpress(https://en.wordpress.com/)isthenumber1platform.Blogger(full-fledgedblog)andTumblr(aninterestingfusionbetweenafull-fledgedblogandaTwitterfeed)areamongthetop3platforms.

Postregularly,butdon'tpostifyouhavenothingworthpostingabout.Ifyouwanttoinvolveothersintheprojectdevelopment,getfeedbackaboutcertaindevelopments,buildthecommunity,don'tjustblogaboutprojectresults,shareyourideas,plans,etc.Commentonotherpeoples'blogs(theynormallyvisitback).

"Twitterisanonlinesocialnetworkingservicethatenablesuserstosendandreadshort140-charactermessagescalled"tweets"(source).There'salotmoretotwitterthanmicroblogging,butit'sastart.

http://webtrends.about.com/od/socialnetworking/a/what-is-twitter.htmhttp://www.wikihow.com/Use-Twitterhttp://mashable.com/guidebook/twitter/

1. Firstcreateusefulcontent:e.g.blog,newsticker,presentation,etc.2. Thentwitter:

140charactersinatweet:Itshouldcontainaspecificpointfromalongerpieceofcontent,orgiveanideaofwhattolearnfromcontent.UseshortenedURLStosavecharacters.Thereareanumberoffreelinkshortenertoolsavailable,e.g.http://ow.ly/url/shorten-urlorhttps://bitly.com/Usekeywords(#hashtags)tofindtopicsandhaveyourtopicsbefound.Use@usernamestoreachuserswithsimilarintereststothat@username’sfollowers.Usepictures.Particularlywhenatanevent.http://www.socialquant.net/images-for-twitter/

Guideforblogging

MicrobloggingwithTwitter

GuideforTwitterbasics:

PublishingResearchSoftwareasOpenSourceonGitHub

41MarketingandPublicRelations

3. KeepingtabsontweetsKeepitundercontrolwithTweetdeck(https://tweetdeck.twitter.com/).Tweetdeckisanicetool,whichgivesyouanoverviewoftweetsfromthoseyoufollowaswellasyours,notifications,messagesandactivities.Twitteranalytics(http://analytics.twitter.com)providesbasicstatisticalinformationaboutyourtweets.

Althoughmostpeoplelookforinformationonlinethesedays,thereisstillaneedforprintedmaterial.Doyouhaveanewproject,software,solution,application?Howaboutacheatsheet/flyer?

Firstofall,beclearaboutwhoyouwanttoaddressandwhatyouwanttoachieve.IsyourtargetgroupUsers?Developers?...?

Tipsforflyers:

Producetheflyerwhenthetopicishot,don’twaitforanevent.Keeptheformatsimpleandeasytoupdate,e.gDINA4singleordoublepaged.Maketheflyeravailabletodownloadonline.IncludeQRcodes(linktohomepage/productpage,repository,i.e.GitHuborotherrepository).

Furthertopics

managingexpectations(openness)

Ifyouworryaboutaname,youmusthavefiguredoutalltheotherissues!

Thefirstthingtoconsideris:DoIreallyneedanameforanewopensourceproject,orwoulditnotbebettertocontributemynewcodeasanextensiontoanexistingandestablishedproject?

Ifitistobeanewproject,takealookatrelatedprojectsandcommunitieswithinthelanguageorframeworkyoubaseyourcodeon.Areabbreviationscommon?Dopeopleusehiporcoolnames?Checkforexistingnames.

Informationdisseminationviapaper–outdated?

Guide:HowshouldInamemyproject?

PublishingResearchSoftwareasOpenSourceonGitHub

42MarketingandPublicRelations

https://www.google.de/search?q=good+software+project+names(trademarks,…)http://www.webdeveloper.com/forum/showthread.php?113873-Great-software-project-names&s=14592899cd3b32c3df12f39bf4616c5e&p=605183#post605183

Tipsfornaming:

FindagoodnameAvoidabbreviationsBevisionaryandchooseanamethatfitstheoverallgoalofwhatyourcodedoes,notaspecificsolutionPreferexisting"realworld"words-theyarealoteasiertoremember

Searchforotherprojectswiththesamename,alsoconsidertrademarks(potentiallyfromcompletelydifferentapplications)Ifaprojectexists,startfromthebeginning

Thisisanopinionatedview.Whatisyourexperience?Getintouchandcontribute!

Furtherresources

...

t.b.d.

Logos

PublishingResearchSoftwareasOpenSourceonGitHub

43MarketingandPublicRelations

Therearemanytasksinopensourceprojectsasidefromactuallywritingcode.Inthissection,wepointtosomearticlesworthreadingpresentingthedifferenttypesofcontributionsyoucanmakeyourselforthatyoucanencourageotherstogiveyourproject.

Thisextensivelistnicelyshowshowmanydifferentwaysthereare-sogetstartednowandparticipateyourselfandmotivateothers.

7WaysNon-programmersCanContributetoOpenSourceProjectsusetheproductbugtestwritedocumentationtranslationevangelisedonatebeprofessional

10waystocontributetoanopensourceprojectwithoutwritingcodeprovidereportscreatefeaturerequeststestthecodewritedocumentationtranslatetheUIanddocumentationanswerquestionsonforumsandmailinglistshelpdesignUI/logo/websitepromotetheprojectprovidehardwarethankthecommunity

14WaystoContributetoOpenSourcewithoutBeingaProgrammingGeniusoraRockStar

startlisteningjoinmailinglistfollowblogjoinIRCchannel

workwithticketsdiagnoseabugclosefixedbugs

workwithcodebetatest

TypesofContributorsandTasks

PublishingResearchSoftwareasOpenSourceonGitHub

44TypesofContributorsandTasks

fixabugwriteatestsilenceacompilerwarningaddacomment

workwithdocumentationcreateanexample

workwithcommunityansweraquestionwriteablogpostimproveawebsite

HowtoContributetoOpenSourcein10steps

Butofcourse,thingsarenotthatsimple.Thefollowingpaperisanextendedreadingonwhatbarriersnewcomersmightface:AsystematicliteraturereviewonthebarriersfacedbynewcomerstoopensourcesoftwareprojectsbyI.Steinmacher,M.A.GraciottoSilva,M.A.Gerosa,D.F.Redmiles,A,InformationandSoftwareTechnology(2014),doi:http://dx.doi.org/10.1016/j.infsof.2014.11.001

PublishingResearchSoftwareasOpenSourceonGitHub

45TypesofContributorsandTasks

Weneedyourcontributionstofillthissectionofthebook.Herewewanttocollectlinksforspecificdomains,suchasbiology,biodiversity,physics,geology,computergraphics,...toprovideastartingpointforresearchers,especiallyPhDstudents,togettoknowexisitingprojectsaswellascommonpracticesintegratingresearchwithopensourcesoftware.

OpenSourceinYourDomain

PublishingResearchSoftwareasOpenSourceonGitHub

46OpenSourceinYourDomain

Thereisagrowinglistofpapersandplatformsthatsupportthepublishingofscientificdataandsoftware.Thisguideismostlyconcertwithcreatingsoftware,thusthissectionisalistof(partiallycommented)linkstoplatforms,journals,repositories,etc.

Pleasenote,dataisnotlikesoftware.WhileGitHubcanbeusedforpublishingandcollectingdataaswell,youshouldseeiftherearemoresuitableplatforms.Thefieldofpublishingsoftwareanddataisanareaofresearchitself:Whynotcollaborateandbeoneofthefirstinyourlab,institutionordomaintoexplorethisavenue?

Theideaof"weaving"code(oneofthetwoaspectsofliteralprogramming,"tangling"beingthesecond)anddataintoasingledocument,forexampleSweaveforRorPweaveforPython,isworthexploringforanyoneusingcodewithinresearch,evenifjustforcreatingplots.

Contributionstothefollowinglistareverywelcome!

ListofsoftwarejournalsbytheSoftwareSustainabilityInstituteEGU2015shortcourse"OpenSciencegoesGeo-PartII:ScientificSoftware",coversjournalsforpublishingsoftwareandplatformsforpublishing(withDOIsetc.)

RecordingsSlides

sciforgeDataCiteZenodoFigshareDryadPANGEARunMyCodeResearchCompendiaVictoriaStodden(Prof.atGraduateSchoolofLibraryandInformationScience,attheUniversityofIllinoisatUrbana-Champaign):Wiki:BestPracticesforResearchersPublishingComputationalResultsEclipseScienceWG...

ScientificPublishingofDataandSoftware

PublishingResearchSoftwareasOpenSourceonGitHub

47ScientificPublishingofDataandSoftware

Thisisthecontribute.mdof52°NorthbestpracticedocumentPublishingResearchSoftwasasOpenSourceonGitHub.Greattohaveyouhere!Hereareafewwaysyoucanhelp!

Youlikethebestpracticeandithelpedyou?Great!Pleasetalkaboutit:

OnTwitter,usingthehashtag#pubopen@fivetwon.Inyourblog,linkingtohttps://github.com/52North/pubopenand/orhttp://52north.gitbooks.io/pubopenWritetous:gitbook@52north.orgInapublication,usethefollowingcitation:Nüst,Daniel,SimonJirka,andAnnHitchcock.PublishingResearchSoftwareasOpenSourceonGitHub.June2015.url:https://www.gitbook.com/book/52north/pubopenBibtexentry:

@Book{2015:52north:pubopen,

Title={PublishingResearchSoftwareasOpenSourceonGitHub},

Author={N\"ust,DanielandJirka,SimonandHitchcock,Ann},

HowPublished={online},

Month={jun},

Year={2015},

Url={https://www.gitbook.com/book/52north/pubopen}

}

Youfoundaspellingerror?Asentencecouldbemisunderstoodandyouwouldliketoclarifyit?

Great!ThisbestpracticeisanopensourcedocumenthostedonGitHub.

Beforeyoucontributeyourchanges,pleasereadtheusedlicense(seeREADME.md)-bycontributingtothisbookinanywayyousignalyourunderstandingofthelicenseanditsimplications.ForktherepositoryonGitHub.Makeyourchangestotherespectivefiles.Splitthemintothematicallysoundgitcommitswithinformativecommitmessages.

Contribute.md

Spreadingthework

Correctingandimprovingcontent

PublishingResearchSoftwareasOpenSourceonGitHub

48Contribute

Createapullrequest.

Thissectionincludesadviceonhowtoaddnewsectionstothebestpractice.

Beforeyoucontributeyourchanges,pleasereadtheusedlicense(seeREADME.md)-bycontributingtothisbookinanywayyousignalyourunderstandingofthelicenseanditsimplications.OpenanewissueonGitHubandexplainwhatinformationismissinginthebestpracticeandwhy.Afterdiscussingwiththemaintainersofthework,forktherepositoryonGitHub.Makeyourchanges.Createapullrequest.

Currently,notranslationsofthebookareplanned.Doyouthinkthiswouldbeuseful?OpenanissueonGitHubtodiscussyourideaswiththemaintainers.

UsingGitHub:http://help.github.com/UsingGitBook:http://help.gitbook.com/Thisdocumentationisnotsufficient?Contributesomethatyouweremissingwhenyoustarted!

Ifyouhavefurtherquestions,contact:gitbook@52north.org

Addingnewsections

Translations

Documentation

PublishingResearchSoftwareasOpenSourceonGitHub

49Contribute

TheFreeSoftwareFoundation(FSF)isanonprofitwithaworldwidemissiontopromotecomputeruserfreedomandtodefendtherightsofallfreesoftwareusers,http://www.fsf.org/

3.6.Guide 3.1.Mindset 3.5.People

TheOpenSourceInitiative(OSI)isaglobalnon-profitfocusedonpromotingandprotectingopensourcesoftware,developmentandcommunities,http://opensource.org/

3.1.Mindset 3.5.People

OpensourcelicensesarelicensesthatcomplywiththeOpenSourceDefinitionandcompletedOSIlicensereviewprocess,seehttp://opensource.org/licenses.

Glossary

FSF

OSI

OSI-approved

PublishingResearchSoftwareasOpenSourceonGitHub

50Glossary