Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Porting guide modernization #626

Open
wants to merge 49 commits into
base: master
Choose a base branch
from

Conversation

abkro
Copy link
Collaborator

@abkro abkro commented Dec 4, 2024

This PR contains the updated and extended UBports Porting Guide.

The guide has been reworked by Ari Börde Kröyer based on the current guide and the contents of the Halium Generic Build Tools scripts using AI assistance. Although the contents are by and large accurate, it is possible that some details need adjustment. The guide therefore needs to be examined by experienced developers/porters to confirm accuracy.

Ari Börde Kröyer added 30 commits November 19, 2024 19:12
Create initial directory structure and basic index files for
the modernized porting guide. This includes:
- Quick start section
- Fundamentals section
- Modern porting methods
- Debugging guides
- Vendor-specific information
- Legacy porting information
- Additional resources
permit building html from the porting-guide-work directory
…tressing clear pathways for different expertise levels.
@doniks
Copy link
Collaborator

doniks commented Dec 4, 2024

image
is this supposed to look like this?

@abkro
Copy link
Collaborator Author

abkro commented Dec 4, 2024

No. That's what the mermaid module is for. It creates a flow chart.

@doniks
Copy link
Collaborator

doniks commented Dec 4, 2024

ah. ugh. damn. probably the jenkins setup ... for some reason the jenkins builds always look a bit different 🙈 we really need to fix this 😒 sorry

@doniks
Copy link
Collaborator

doniks commented Dec 4, 2024

So. I'm trying to read this, but my first impression to be honest is I get lost all the time. I never know where I end up after I click on a suggested step and end up going back to the start page and trying all over.

It seems to me the new organisation is making a lot of accomodations for an "expert" and tries to anticipate what that expert needs, while still writing all the content. And I have the feeling the result is so full of "hey maybe you want to go here or there"-pointers and "this is for experts"-disclaimers that it just becomes hard to read for ... I think for everyone. I'm wondering whether it's worth it to invest so much in this non-linear structure for some "expert" ... I'd say if they are experts then they will have no problem scanning and skipping to get to what they need. And if they are not able to scan and skip because they don't understand the content and the relevance ... well, then they are probably not actually experts, just impatient.

@doniks
Copy link
Collaborator

doniks commented Dec 4, 2024

ok. I'm slowly getting somewhere. I start from fundamentals. Always ignore any "maybe you want to" parts. Read top to bottom. At the bottom click "next"

I really like the content! it gives much clearer overview of what's the purpose of which part. I love the summaries on the top! with the navigation I still feel a bit challenged

@abkro
Copy link
Collaborator Author

abkro commented Dec 4, 2024

I could probably tone down the "expert/novice" pathways a bit without too much trouble, but I do think it wise to let the different sections start with the main steps in brief, whatever one wishes to call it. "Quick start" or "Steps in brief" or just "In brief" or any better suggestion you might have?

But maybe we can try it out this way first while completing what is still missing and then adapt it?

Still missing:

  • The section on finalizing the port. I need either reliable sources for this, or a reliable source (person) to discuss it with.
  • The section on transitioning a xenial port to focal. Ideally written as generically as possible (if possible), to allow for subsequent releases,
  • And less crucial: Adding relevant links/sources to the additional resources section at the end.

@abkro
Copy link
Collaborator Author

abkro commented Dec 6, 2024

Let me know if there's anything in particular that you're expecting from me. Otherwise, I will just try to address a couple of the points I mentioned above, when I get the chance. I will also check if there is anyone who can help me with the section on finalizing the port. But the things I mention here can be added in an iteration, so they're not really necessary for a first release, in my opinion.

The mermaid visuals need to build and display properly, though.

@doniks
Copy link
Collaborator

doniks commented Dec 6, 2024

yeah, my feeling is the disclaimers and pointers could be thinned out a bit.

I agree to keep the short preambles on top of pages to give a summary. That is super helpful.

Wrt missing parts - I would say, ideally we're not removing anything that's already there and is not meant to go away. So, if finalizing is missing in the sense that the existing content hasn't been moved into the new structure, then I'd say that should be fixed before publishing a new version. Any other parts that we don't have today shouldn't block a publication. And in fact going in iterations is often easier than in a big bang.

Wrt mermaid, I'm leaning towards kicking that can down the road. I can see them when I build locally, and I expect that they would build correctly once they are merged. I forgot the details, but I think the CI takes some parts from main branch, or from some vanilla uncustomized setup or something. So, I think that is the reason why the CI build of the PR doesn't look right, but I expect this would not affect the actual build of the site once merged. Now, of course it would be great if we could improve our CI build, it actually has a couple of rendering problems (links, etc), but again, that's a separate problem and shouldn't block a merge of this porting modernization.

What I think does need to happen is a full review. There should be at least four eyes that agree with the new structure and content. While I'm happy to review it in detail, it will take me some time to finish it, since it is quite big. If someone else wants to step in and do a review I'd certainly welcome it!

Maybe just one more thing that I noticed: In the current version the navigation looks like this:

image

ie a section "Porting" with a couple of chapters

The PR looks like this:

image

ie a section "Porting" with a single chapter called "Ubuntu Touch Porting Guide". The "Ubuntu Touch" seems redundant, but moreover everything is collapsed into a single chapter. I like it better if the hierarchy is that one level flatter and we could pull the content chapters up by one level. But I can't really suggest a useful set of top level chapters because I haven't managed to understand and digest the newly proposed structure

@abkro
Copy link
Collaborator Author

abkro commented Dec 6, 2024

I'm busy on Saturday, but I'll try to follow this up on Sunday. By the way, I agree fully with the need for more eyes on the content mainly, but also the structure. However, my posts in the porting group, and the mention in the last Q&A have not triggered any interest.

I wonder, is it because I am the one doing this, and people have seen the many dumb questions I have asked in this group, so they assume the result is just garbage? Or maybe it's down to a general lack of knowledge about AI, so they think this is pure fiction? Or is it simply that they're too busy with other stuff? My point is that if you know how to enlist someone with the necessary knowledge to go through this, please help to make it happen!

In the meantime, I will be working on addressing the points you mentioned.

@doniks
Copy link
Collaborator

doniks commented Dec 7, 2024

Ah. No. Please don't take it personal! Anyway there is no such thing as a dumb question. From where I sit its just that there is not much contributions to the porting docs, or even the docs overall. And yeah it's probably a mix of lack of knowledge or lack of courage or lack of time. To me you're just one of the few unsung heroes keeping the porting docs up to date. Much appreciated! I wish I could recruit more contributors or reviewers, but it is what it is. Which probably also means that you are stuck with me as a reviewer:) I sense you would wish for someone with more porting know how than me, but well that's also just how it is. And of course it's all volunteer work and people should scratch their itches and otherwise everybody has a life outside so noone to blame, we just make do with what we have 💪

@doniks
Copy link
Collaborator

doniks commented Dec 7, 2024

Ah one other small feedback: I think you can remove the "this is work in progress" disclaimer now. That's understood

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants