Find the right structure for this repository, and the right needed processes

[LouisCAD]

We need to figure out how we can have a developer-oriented "database" for the OEM issues the community found about, in a form that:

1. Is easy to browse
2. Gives a helpful amount of detail
3. Is as future proof as we can find
4. Allows to easily follow updates about a particular OEM issue, while filtering chatty discussions about it.

Once we figure that out, we can write down the processes we have to:

1. Have people submit a new OEM issue
2. Have people submit new information about an OEM issue
3. Integrate a valid submitted issue into the "database"
4. Broadcast important updates about an OEM issue

We might make use of tags and of limiting conversation to collaborators for issues that are designed for updates about an OEM issue already integrated into the database.

Any ideas are welcome as we prepare this to get the repo out of the WIP status.

[OyaCanli]

I think, in order to make it "easy to browse" issues seem to be a good idea, as proposed in FR community. We can search with key words in issues and we can search by labels. And we can have a contents page (in readme) where we categorize issues (by APIs may be?) with links to corresponding issues. And it is possible to subscribe to issues, so everyone can follow the issues they are interested in.

I searched a bit new Github Discussions, in case it could be an alternative. Many aspects are similar to issues, we can search by and filter among discussions as well, we can subscribe to it. What is more, there will be upvoting feature soon in discussions (not there yet). There are no labels, on the other hand! But there are (customizable) categories instead. So I guess it could be an alternative, though I don't see a major advantage over issues.

One possible arrangement is to accept OEM issues as "issues" and all other meta-discussions and requests as "discussions". And if someone accidentally creates an issue for something that should have been a discussion, it is possible to convert the issue to a discussion.

In both cases only moderators can create new categories or labels. So that's something to consider. I guess we can't add labels for all available device models. May be we can add only for brands? (huawei, samsung, etc) Possibly for Android versions? Or major APIs? We'd probably need a discussion topic like "label request".. But we risk having a label explosion!

What do you think about it? If there are any different ideas, they are very welcome!

[MaximeFERRIER]

In my idea, I imagined a ReadMe with a summary, a list of APIs or UI components with an issue, then for each one an array with the API's class, the device (Android API), the software (version) and a description of the problem. Create another column with the link of the discussion about the issue is a good idea, maybe someone has a solution.

Summary

• androidxnavigation
• [...]

androidx.navigation

Class	Device	Software	Issue	Discussion
androidx.navigation.fragment	Nokia 7+ (API 29) Samsung Galaxy S10	Android One One Ui (2.0)	Here the description of the issue	Shortcut to the discussion

Or

Class	Issue	Discussion
androidx.navigation.fragment	Here the description of the issue	Shortcut to the discussion

OEM concerned	Device	Software
Nokia 7+ (API 29)	Android One
Samsung Galaxy S10	One Ui (2.0)

I'm open to any suggestion to improve this.

[LouisCAD]

@MaximeFERRIER Did you comment just to rickroll us?

[MaximeFERRIER]

Nop. My biggest problem with using an array to classify data is when you want to add several phones in a single column. Maybe we could merge the device and the software ?

[LouisCAD]

I'm wondering if a relational database wouldn't be the right choice, but diffing a sqlite db file in git will not be nice.

[MaximeFERRIER]

A dB would be perfect, but a bit hard to contribute. If we create a website hosted by GitHub directly, we could use a json file "as db". It would be easier to contribute and for us, to format data.

[OyaCanli]

Yes, databases are great for sorting and filtering, but it is also important that it should be easy to contribute for android developers and easy to maintain for us.

If there will be literally a db file in the repo, the developer has to download and add and we will also have to download and check before merging. And if there are multiple adds at the same time, I don't know if git can detect the conflicts inside a db? I guess no, right?

A website could be a good alternative, and it can be arranged to make it easy to contribute and maintain. But it requires a considerable work in the beginning. And we are a group of Android developers, my competence in web development is very limited. May be you have more experience with web? We had collaborated on a website project with our android developer class at Udacity in the past. It was made by Jekyll and it was indeed easy to contribute and maintain: https://github.com/google-udacity-scholars18/google-udacity-scholars18.github.io But we had a full-stack developer in the team, who spent some time creating it in the beginning.

In fact I have also another idea. This might be stupid but it would be very easy to create and maintain: link to a simple public google excel sheet in the readme. Anyone can easily contribute online (we can make it require approval from file owners) and anyone can check it out online, or grab a copy, sort, search, filter..

[MaximeFERRIER]

The public sheet is a good idea to start quickly, but I'm not sure on the long term. I didn't know we could add an approval :o I don't have a huge experience in web development, but a simple page could be doable even if it's not our specialty ^^ Just keep in mind GitHub's website are limited, no PHP for example. I'll check restrictions about js. (EDIT : we can use js (not a rickroll))

[LouisCAD]

If we were to make a server, I think it'd make more sense to use Kotlin rather than PHP 🙃

Regarding an sqlite database, we might work with insert SQL statements in PRs.

Another thing we can do is an Android app where every issue is demonstrated, with the workarounds when possible. Might also help people figure out which devices are affected exactly.

[OyaCanli]

Regarding an sqlite database, we might work with insert SQL statements in PRs.

I didn't know that this was possible. Can you recommend me a resource/tutorial etc for learning how to do that ?

[OyaCanli]

Or am I misunderstanding? Do you mean it is possible that someone can add a row to a db directly through a PR, using SQL statements? Or you mean, they make a PR as an SQL statement to avoid downloading the database? (And we copy paste on our side)

[LouisCAD]

I mean we can never have the actual .db file in the repo and keep generating and populating it in CI based on the new insert statements. But I'm not sure it's a good idea for our use case, especially when I compare it to having an app with the reproducers.

[LouisCAD]

I think I finally found a motive to follow this Kotlin web app hands-on: https://play.kotlinlang.org/hands-on/Building%20Web%20Applications%20with%20React%20and%20Kotlin%20JS/01_Introduction

[OyaCanli]

Ok, I misunderstood :o) Yeah, I don't think having a .db file in the repo is a good way, either. A JSON would be easier to contribute and easier to consume both in a web or an Android app, right?

In fact, whether we do a web app or/and Android app, can't we directly filter through issues using Github REST API? May be we wouldn't even need a seperate database (a json?) in that case? That would make contribution very easy, as contributors will only need to create an issue and nothing more.

[OyaCanli]

I checked out docs a bit and I think it is pretty much possible : https://docs.github.com/en/free-pro-team@latest/rest/reference/issues

Though, if we create our own JSON, we'd be more flexible, we'd shape it according to our needs, it would be easier to query and we'd avoid too much dependance to labels.

What do you think?

[MaximeFERRIER]

I agree. I found an example (we can change the template for a simple Bootstrap one, but a hosting on GitHub is enough).

I'll try to make a poc while I'm on vacation, I promise nothing ^^

(If I don't show up during this week : Merry Christmas ! )

[MaximeFERRIER]

I created something quickly, you can dl it here To open it with Chrome (for example), use arguments --args --allow-file-access-from-files

I used Bootstrap for the design, JQuery to read and parse the json file with issues and MustacheJS to create a dynamic template.

The architecture used is like this :

.
+--css
+--data
---+--issues.json <-- The file to modify to contribute
+--imgs
+--js
+--theme
+--index.html

Oc, feel free to comment and suggest improvements.

[OyaCanli]

Oh! Thanks a lot for taking your time doing this @MaximeFERRIER ! A good start! We can iterate on the user interface but I think the first thing to discuss is the data model. And to determine what we need in the data model, we need to think what the developers would like to do on the website/android app. I guess we would like give a good overview, but most importantly good filtering options, right? So I think the model should be suitable for providing several filtering options.

More concretely, full class names seem fine for overview, but if a developer will make a search using a search box, s/he wouldn't like to type the full classname. If the list gets longer later, instead of scrolling everything, I would prefer to type "navigation", "bluetooth" etc and get the related issues. So, I think we should consider this while creating the model. May be replacing full class names with simple class names, or keeping the class names but also adding short class name? Or adding a field for keywords/tags?

[MaximeFERRIER]

I've created a new branch with this first attempt. Feel free to modify it (yep, we use GitHub and I pushed my code on my NAS ><). For the data model : as a developer, when I have a bug in production on a specified API on a specified device, I would like to check if it is a known issue and see if someone found a solution (otherwise, create a discussion to ask for help)

Do you have other needs in mind ?

For the website : The first part is the summary of every API with issues on the website. If you think we should add a search box, maybe we should add in the data structure the "generic term" of an API (navigation for androidx.navigation). What do you think ?

[OyaCanli]

I mean, searching functionality is not urgent. In fact, even website or android app are not urgent in my opinion. In the beginning, there won't be too much issues and people can easily browse through issues section on github. There is already a search field there. Only, when(if ever) it begins to get too long, it's going to be better to have an app for better overview and filtering options. But if we're expecting people to contribute to the JSON file, we'd better decide it's structure in the beginning, considering future needs. And I think, once we decide the general process of contribution and the data structure, we can open it to contributions even if the web and/or android app is not ready? What do you think?

For the data model, I agree, as I told before, related api could be a generic term as you put it, like "navigation".. So that it would be easier to search. Is there a specific reason you preferred full class names @MaximeFERRIER ? (I don't know, to avoid possible confusions? )

And I think there should be a field for android sdk level, but as it might concern multiple api levels, I'm not sure about how to put it. Like <24, 26+, or 25-30 etc?.. Any ideas?

[OyaCanli]

By the way, regarding a small detail on your previous post, I didn't think of this repo as a place to "ask for help". If a developer has a specific problem, s/he can ask it on Stackoverflow and s/he'll have a better chance of a fast response.

The problem I saw, and the reason I proposed you to make a list together, was the problem of not being aware of oem specific potential problems and bugs in advance. If I'm working on an app that uses Camera Api, I would like to come to this repo and browse all issues related to camera api, so that I can be aware of potential problems in advance, try to find solutions in the early stages of production and I can detect which devices are most likely to cause problems and I'll try to find testers with that device. That's not something easy to search on Stackoverflow.

Of course, someone who has already a specific bug can also come here, browse and profit from previous discussions. And if they can't find something related to their issue, they can contribute by adding it. But if they are currently in trouble and expecting to find urgent help, and they couldn't find anything related in this repo, I think it is better to ask it first on StackoverFlow. I mean, it is possible to find some help here as well, as others having the same problem continue the discussion, but that might be months later..

I mean, I'm expecting developers to contribute to this repo primarily by sharing their experiences, so that we can have a huge list of reference that they can also profit themselves.

That's how I thought, but if you imagined it differently, we can of course discuss it further.

[OyaCanli]

@LouisCAD Do you have remarks about the discussion so far? Do we at least agree that we make a JSON that developers can contribute (which will be consumed by a web and possibly android app?)

[OyaCanli]

We made some progress after some private discussion and I'd like to write a short summary of our progress here in case anyone reads:

• We preferred Github discussions instead of Github issues as the home of OEM-issues. This way, Github issues can serve to their original purpose. Github Discussions meet our needs as well, and different than Github issues, in Github discussions we can filter by categories and votes.
• We'll request devs to contribute to a JSON file. Maxime made a website that consumes this JSON. It is simple for the moment, but it does the job, and we hope to improve it later. We updated a bit JSON structure, considering that we might want to add different filtering options to the website in the future.
• Categories in Github Discussions is limited to 10. So we can't make a category for each api/topic. But I added some categories with the aim of grouping discussions and providing some filtering. (As website doesn't provide advanced filtering for the moment, we can profit from filtering options within github discussions as well) But I was really not sure how to group issues. So ideas, feedbacks are welcome.

Feedbacks for any aspects are welcome.