search

cgeo / cgeo

c:geo - The powerful Android geocaching app.
www.cgeo.org
Apache License 2.0
1.39k stars 566 forks source link

Architecture Decision Record #9052

Open Lineflyer opened 4 years ago

Lineflyer commented 4 years ago

Taken from https://github.com/cgeo/cgeo/issues/9045#issuecomment-697934215

BTW I think it's not the first time there are some discussions happening due to lack of documentation of decisions from the past. What about at least thinking of having something like ADR for c:geo, @Lineflyer ? =)

I always get new ideas here, that why I like working on such projects. The idea is simple, the question is whether the Github Wiki can serve the same purpose and whether someone is really willing to create such documentation.

Narrat commented 4 years ago

Can a single Github wiki page exluded from editing by everyone? If that is possible, why not. On the other hand personally i would add a page with those informations (however it is organized) to cgeo.org, which is linked from cgeo.org/development.

rsudev commented 4 years ago

I don't think it is necessary to prevent editing, as all content is versioned and unwanted edits can be reverted if necessary. Whether it is in the cgeo wiki or in the cgeo github pages might not be too relevant (the wiki page could be linked to in the readme)

Narrat commented 4 years ago

Indeed a nice benefit that the wiki is in version control, but if such unwarranted and unwanted edits happen, they do pollute the history, can go unnoticed for some time and need to be actively undone. My thought process for the argument. Regarding where to place. Depends where the team makes the difference (propably development vs end-user) regarding what is added to the github wiki and what to the cgeo wiki. (Personally I would gather every information in one place and avoid having two platforms where information could be found shrug)

eddiemuc commented 4 years ago

The idea of documenting important decisions togehter with their reasoning is definitely a good one. I am in favor of a simple wiki page and some table structure (with columns e.g. "Decision", "Reasoning", "Decision Date", maybe "Contact" (if someone has further questions in the future)), maybe divided in categories (e.g. "GUI Design", "3rd party Libraries", "Supported devices", "Used technologies", "Database" etc).

But please beware of making this thing too complicated or formal. I do want to spend our limited time capacities in making c:geo a greater product with cool features and less bugs, not in filling templates and maybe review/approval processes... (I have enough of that in my work place).

Lineflyer commented 4 years ago

I would think the best method is using markdown files directly in our repository (e.g. /main/project/ADR/) with sub dir structure like "/database", "/user_interface", etc.

eddiemuc commented 4 years ago

I would think the best method is using markdown files directly in our repository (e.g. /main/project/ADR/) with sub dir structure like "/database", "/user_interface", etc.

That's a good idea too, but does that mean you have to perform a pull request every time you want to change something?