search

okffi / open-api-definition

Community governed definition of open API
http://okffi.github.io/open-api-definition/
Creative Commons Zero v1.0 Universal
7 stars 7 forks source link

Roadmap. Tässä keskustellaan siitä, miten uusia versioita määritelmästä tuotetaan #36

Open Mygee opened 8 years ago

Mygee commented 8 years ago

Avaan keskustelun siitä, miten usein uusi versio määritelmästä tehdään ja miten prosessin pitäisi toimia. Taustaksi. Alkuperäisen määritelmän sisällöstä käytiin keskustelua kuukausia. Määritelmä yritettiin laatia niin, että siinä ei olisi aukkoja. Tarkoituksena oli hyödyntää määritelmää ohjelmistojen hankinnassa. Aiemmin melkein mitä tahansa rajapintaa saatettiin kutsua "avoimeksi rajapinnaksi". Viimeaikoina määritelmän käyttö on laajentunut siihen suuntaan, että sen avulla kehitetään uusia rajapintoja. Määritelmän päivittämisessä haetaan tasapainoa pysyvyyden ja kattavuuden kanssa. Lisäksi halutaan pitää ihmisen motivaatiota osallistua määritelmän tekoon ja hyödyntää määritelmää käytännössä yllä.

Mygee commented 8 years ago

Ehdotelma muokkausprosessiksi image

apoikola commented 8 years ago

Kohtaan 2 (ongelmien kerääminen) syöttökanavina muitakin, kuin github-issuet, eli valitaan tietyt kanavat (meililista, drivessa oleva kommentoitava tekstiversio, tapahtumat, yms.) missä voi kertoa ajatuksiaan ja @Mygee ja me muut aktiivit huolehdimme siitä, että identifioidut asiat avataan issueina tänne. Avoinrajapinta.fi sivulla sitten kerrotaan nämä kanavat, missä voi antaa palautetta määritelmään.

"Ryhmä keskustelee" - kohtaan voisi laittaa, että tavataan myös livenä tarvittaessa, voidaan pitää "issueiden clousaus-talkoita" tms.

Tekstin kommentointi Gdocsissa on varmaan tarpeellinen, koska on idioottimaista avata issueita tyyliin kolmannen kappaleen riviltä kaksi puuttuu pilkku.

Tärkeää viestiä, mikä on issuen ja mikä tekstikommentoinnin rooli. Voi ihan hyvin olla, että ensin kommentoi jotain tekstiin ja jos osoittautuu, että kyseessä ei ole vain triviaali pieni parannus, vaan joku asia, joka herättää enemmänkin keskustelua, niin avaa sitten siitä issuen.

Viimeisessä kohdassa "valmiin version" julkaisu Githubissa kannattaa sopia vähän tarkemmin, mitä tarkoitetaan valmiilla. Voisi olla niin, että aika-ajoin drive kommentointiversiosta "putsataan" etabloituneet muutokset siirtämällä ne Githubiin ja julkaisemalla uusi versio numero, ks. https://github.com/okffi/open-api-definition/issues/32

Passiivimuoto: tehdään... ryhmä keskustelee vähän haastava, voisi olla ainakin muutaman nimetyn prosessin fasilitaattorin joukko ja sitten sopimus, että esim. ne livetapaamiset (myös etäosallistuminen mahdollista) ovat niitä keskustelun ja pätöksenteon paikkoja, joihin kannattaa sitten osallistua tai antaa ainakin näkemyksensä etukäteen hyvin tietoon, jos haluaa vaikuttaa.

Tämän voi sitten julkaista täällä githubissa wikisivuna.