Skip to content

Latest commit

 

History

History
317 lines (212 loc) · 17.2 KB

how_to_work_github.adoc

File metadata and controls

317 lines (212 loc) · 17.2 KB

Hur vi jobbar med Öppen Källkod på GitHub

Table of Contents
Note
 Är du aktiv på Digg’s GitHub-ytor, läs igenom detta dokument, och Kompletterande länkar.

Inledning

En översikt av hur Digg jobbar på samarbetsytorna för öppen källkod. [1]

Digg har idag två externa samarbetsytor för för öppen källkod och öppna samarbeten på GitHub. Där samverkar man kring diverse projekt, både med externa konsulter, bidragsgivare, och Digg-anställda. Huvudsakligen ligger där programmeringstunga-projekt, men det förekommer även rena dokumentations- och specifikations-projekt.

Note
 Vad gäller Öppen Källkod-projekten på Digg’s GitHub-ytor, som tas fram på direkt beställning av Digg och är direkt avsedd för deployment på Digg’s drifts-miljöer gäller att projektet också SKA kunna byggas och deployas i Digg’s interna miljöer. Se i det fallet intern Digg-utvecklardokumentation (utvecklarhandbok) för detaljer.
Table 1. Samarbetsytor
GitHub-Organisation Samarbetsyta Syfte Huvudansvariga Not

DiggSweden

GitHub

Release av egna lösningar, samarbete med andra

ospo@digg.se (Digg OSPO/Open Source Guild)
GitHub-användare med rollen Owner

Rollen Owner: Ej extern info.

SwedenConnect

GitHub

De flesta SwedenConnect-relaterade projekt.

GitHub-användare med rollen Owner

Rollen Owner: Ej extern info.

GitHub-konton

Du behöver till att börja med skaffa ett GitHub-konto.

  • Tänk på att ditt konto är i viss mån offentligt och kan komma att indirekt också kopplas med Digg

  • Du väljer själv om du vill lägga till din <namn@digg.se>-epost-adress till ett befintlig GitHub-konto, eller skapa ett helt nytt GitHub-konto för din Digg-personlighet. Enklast brukar vara att bara lägga till <namn@digg.se> till ditt befintliga kontos epost-adresser.

  • Oavsett vad ditt användarnamn är, se till att också fylla i ditt riktiga namn (GitHub→Edit Profile→Name).

Säkerhet för ditt GitHub-konto

Vidare, om du ska bidra till projekten med Pull Requests:

  • Genomför inställningarna för att signera dina commits: Signera commits

TO-DO: image of signing

Att lägga till en användare till DiggSweden

Du behöver sedan gå med i Digg’s GitHub-organisation, och bli tillagd i ett eller flera Team.

Det finns flera olika möjliga vägar in i organisationen:

  • Du skickar ett mail till <ospo@digg.se>. Ange syfte och tänkta behov.

  • Du får en inbjudan till ett team för ett projekt eller tillhörighet t.ex. ett konsultteam, av någon admin/owner på DiggSweden.

Rollerna i vår GitHub-organisation

Det underlättar användandet om du har grundläggande kunskap om rollerna vi använder på GitHub.

  • Owner - superadministratörer för organisationen i sig.

  • Member - alla inbjudna till organisationen. Ska läggas i olika Team för tillgång til specifika repos/projekt.

  • External Collaborator - externa användare som inte är inbjudna till organisationen men ges enskilda rättigheter.

Note
 En GitHub-Organisation kan ha fler än tre roller, se organisationsroller

Member-rollen

Member har i sin tur en mängd finare roller som styr vad de kan göra i ett repository. Exempel är admin, maintain, read Se repository-roller.

Admin-rollen och dess ansvar

Varje GitHub-team ska ha en eller flera användare i rollen som Admin. En Admin förväntas ha övergripande översikt om sitt Team och dess projekt och:

  • ta ansvar för att agera eller delegera ansvaret för sitt teams/s:

    • säkerhetsvarningar

    • ta bort användare ur teamet som är inaktiva

  • ta ansvar för att projekten arbetar i övrigt för god projekthälsa genom att följa rekommenderade konventioner, (se Kompletterande länkar).

  • vara teamets/ens första kontaktyta med Owners för adminstrativa spörsmål vid behov.

External Collaborator-rollen

Undvik i första hand denna roll. Istället för att lägga till 'External Collaborator' så rekommenderas det numer att man vid samarbeten lägger användare i ett GitHub-team, nytt eller befintligt. På så vis regleras behörigheter till repositories för en grupp användare, de i teamet, istället för hantering av behörigheter riktade mot en specifik användare. Det ger en mycket bättre separation och översikt över användaren och vilka rättigheter användaren har.

Checklista, mallprojekt och rekommendationer

Hjälpmaterial, rekommendationer, checklista

Digg har tagit fram hjälpmaterial för Öppen Källkod-projekt, i form av interna riktlinjer, checklista samt mall-hjälp, se Kompletterande länkar.

Basmall för GitHub-organisationen DiggSweden

Ett projekt som läggs på DiggSweden’s yta kommer att, som förvald standard erhålla generella GitHub-mallar för felrapporter, nya funktioner/förändringar och Pull Requests. Anpassa dessa efter projektens behov. Vad som är förvalt kan du se i Digg’s bas för organisationen DiggSweden, Kompletterande länkar.

Förvaltning och livscykelhantering

Ärende/Issues-hantering

  • Ansvar för ärende/issue-hantering i första hand.

Teamet som äger ett repository tar i första hand ansvar för att svara på ärenden/issues. Hur team lägger upp det i detalj är upp till Teamet.

  • Att svara på ärenden/issues

I grund och botten är vår GitHub och projektytor avsedda för projektfokuserade ärenden. Vi försöker styra undan diskussioner som inte rör projektet direkt till andra ytor som Dataportalens Communityforum (se Övriga länkar). Tveka inte att vidarebeforda frågor till exempelvis Digg’s kundtjänst. Exempel kan vara frågor som inte är av teknisk karaktär, eller som inte rör projektet mer specifikt.

Tip
 Vi är en myndighet, och förväntas av allmänheten besvara vänligt, korrekt och inom rimlig tid. Rekommenderad svarstid för ett ärende är fem dagar.

Hantera inaktiva medlemmar

  • Se till att inaktiva medarbetare lämnar GitHub-organisationen (Admin-rollen för teamet håller översiktlig koll, kommer automatiseras).

  • Inaktiv användare inom GitHub-organisationen rensas automatiskt efter ett år. TO-DO

Arkivering av projekt

  • Om projektet inte är aktivt, det vill säga, har ingen förvaltare längre, så SKA det arkiveras, och detta BÖR helst tydliggöras i dess README.

Sårbarhet och säkerhet

GitHub bjuder på en mängd verktyg för automatiserade sårbarhet- och säkerhetsgenomsökningar, inklusive beroende-kontroll och statisk kodanalys. Vi aktiverar i princip allt som blir tillgängligt inom detta område för GitHub. Se Förvalda GitHub-inställningar för vilka funktioner som är aktiverade. Förinställningarna kan sedan behöva finjusteras av teamet.

TO-DO: Add image of GitHub Security tab

Publicering av externa bibliotek och container-avbildningar

Warning
 Work-in-progress, hoppa över detta stycke (Kommer avhandla de publiceringsställen vi redan har publiceringskonton på , i slutändan kanske eget doc, publicering. Ett migrationsarbete pågår här.

Externa biblioteksytor

Publicera inte paket på externa ytor i Digg’s namn, men med personligt namn som avsändare.

Använd ospo@digg.se som avsändare. Detta för att undvika personberoenden i framtiden, eller än värre, inaktuella epost-adresser.

NPM

Vi har i skrivande stund två organisationer på NPMJS - digg, samt diggsweden.

Det som ligger under 'digg' ska arkiveras, och det är organisation diggsweden som ska användas i framtiden.

Maven Central

TO-DO

GitHub Registry

<TO-DO> detta ska vi också reda i , chainguard med mera att rekommendera för licens o säkerhetskompatibla image-avbildningar. * Om du publicerar container-externa images, föredra små säkra bascontainrar som distroless, Wolfi.

…​

Vanliga frågor (FAQ)

Team

  • Hur skapar jag ett GitHub-team?

    Be någon som har Owner-rollen på GitHub, eller kontakta ospo@digg.se för att skapa ett GitHub-team.

  • Hur ska team delas in - per produkt, konsultgrupp eller vad?

    Befintliga team delas ibland upp på ansvarsområde, ibland på konsulttillhörighet, ibland projekt. Avgör vad som passar er bäst. En 'Member' kan vara medlem av många team.

  • Ett team ges ju tillgång till ett eller flera repositorys - vilka rättigheter ska de ha som default/standard?

    Det förekommer ej säkerhetsklassade personer i ett team, så ett repositorys skrivrättigheter SKA vara "Read/Läs" för teamet. Sedan får Admin för teamet, efter behov, se till att behövande medlemmar har rättigheterna de behöver "Write", "Maintainer" etc.

En 'Member' kan vara medlem av många team.

  • Jag vill forka ett externt projekt, ska jag göra det under Digg’s GitHub-organisation eller under min privata användare?

    I de flesta fall så säger vi nej på att lägga forken under Digg-organisationen, forka under din användare i första hand. Vi vill inte att organisationen DiggSweden ska ses som att man har tagit på sig att förvalta en fork av något projekt. Forkar som ligger under organisationen och inte har diskuteras om i förväg om kommer att arkiveras.

Schrems II, GDPR

Bidrag

  • Får vi bidra med felrättningar och issues uppströms?

    Vi har inte arbetat fram en formell guide och formen för detta än, det ligger på framtida agenda. Notera att detta redan sker i praktiken - Digg bidrar redan aktivt till Öppen Källkod och data genom upphandlingar och samarbeten med externa partners där vi uppmuntrar och kräver Öppen Källlkod. Bidrag nämns i våra interna riktlinjer.

Privata och publika projekt

  • Varför har vi (eller extern samarbetspartner) privata projekt på GitHub, är det inte en plattform för Öppen Källkod?

    Det finns flera skäl till att projekt bör vara privata på GitHub under en fas. Ägarskapet inte är klart, man har inte bestämt om ett äldre projekt från annan organisation ska bli Öppen Källkod eller ej, man behöver kvalitetkontrollera projektet innan det blir Öppen Källkod och så vidare. Premissen är dock att privata projekt ska samarbetas om på lämpligare (stängda, säkrare) ytor, och endast i undtagsfall och medvetet val, på GitHub.

  • Jag har bara fler frågor nu. Var ska jag vända mig?

Maila i första hand <ospo@digg.se>, i andra hand kontakta någon av Owners så kan de hjälpa dig vidare.

Terminologi

Table 2. Terminologi i detta dokument
Begrepp I detta dokument avses

Arkivering

Användning av ett projekts Arkivering-funktionen på GitHub. Det betyder att projektet är fortsatt öppet och åtkomligt på GitHub, samt berättar för omvärlden att det inte har någon aktiv förvaltning.

Besvara ett ärende

att besvara en Issue eller Pull Request. Minimalt bekräftas att ärendet är läst. (Det kan också i sig innebära lösning eller avslut i samma bekräftelse).

GitHub-Organisation

En samarbetsyta på GitHub kallas Organisation, och en Organisation innehåller en mängd repositories.

Inaktiva användare

Medarbetare (anställda, konsulter) som slutat, uppdraget upphört, inte är eller planerar vara aktiva på Digg’s GitHub över längre tid.

Projekt

Övergripande samlingsnamn som kan implicera flera kodrepositories eller GitHub-team.

Påhittat exempel:
Projektet covidbevis, består av teamen 'digg-interna', 'konsultTeam2', och de har tillgång till repositories covidgui, covid-sad

Team

Här konstruktionen GitHub-team som kan ses som virtuella team.

Samarbetsytor för öppen källkod

Idag, våra två ytor på GitHub. Dokumentet berör ej interna, icke-publika ytor.

Workflows

GitHub’s benämning på CI/CD-Pipelines. En rad konfigurerbara processer för att bygga, autotesta, deploya projekt som körs på GitHub’s servar, så kallade Runners.

Förvalda GitHub-inställningar

GitHub har flera bra funktioner för säkerhet, adminstration och förvaltning, och många av dessa måste aktiveras. Detta avsnitt beskriver en del av de inställningar som är aktiverade på DiggSweden.

Syftet är inte att dokumentera alla detaljinställningar i tabellen, men att ge en översikt så att användare förstår vilka möjligheter de har i sina projekt.

Namn Inställning Effekt

Basepermission

No Permission

En nytillagd medlem i organisationen har inga rättigheter. Det innebär att hen inte ser andra projekt, team, privata repositories etc., utan bara det som är publikt, eller för de team som hen blir tillagd i. Basrättigheter

Forking and creation of private repositorys

Aktiverad

En användare kan skapa samt forka privata repositories.

Require approval for first-time contributors to run GitHub Actions

(activated by default)

En nytillkommen bidragsgivare i ett repository kräver ett explicit godkännande vid första bidraget för att få starta ett Workflow.

Dependency Graph

Aktiverad

Beroendeanalyser för repositories.

Dependabot

Aktiverad

Skapar automatiska Pull Request för sårbarheter samt utdaterade beroenden. Finjustera inställningar för ditt projekt.

Secrets Scanning

Aktiverad

Genomsöker repositories efter nycklar, lösenord etc.

Code Scanning

Aktiverad

Genomsöker kodbasen med SAST-analys. CODEQL. Finjustera inställningar för dina repositories.

Standard-bas för organisationen DiggSwedens Organisations-basrepo

Aktiverad

Ett mall-projekt som innehåller projekt-förinställningar för GitHub-organisationen "om projektet inte anger något annat". Se dess README för vad det täcker. Det är högst möjligt att du vill finjustera dina projekt om andra behov.
Caution
 Flera av de beskrivna inställningarna gäller inte om du använder privata repositories, då det kräver en betalplan för GitHub.
1. Detta dokument har specifikt DiggSweden i fokus