Porting guide modernization

[abkro]

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.

[abkro]

While we're still at it, could you please also serve D3 Javascript file locally as well?

[1]:

content-security-policy: sandbox allow-same-origin; default-src 'none'; img-src 'self'; style-src 'self';

Did this now.

I also completed and added a first version of the bibliography section.

[abkro]

I had some time on my hands, so I improved and extended several of the configuration sections.

[peat-psuwit]

Ok. I have a chance to read the change a bit more, and I think AI hallucinates too hard on this one. Probably a good idea to proof-read the whole thing first?

[abkro]

@peat-psuwit
General info about my limited coding background/experience and how I have worked.

Myself:

• I hold degrees in marine biology and educational management
• I have used Linux for 20+ years. Needed to constantly recompile the kernel during the early years in order to enable my specific hardware.
• I have followed basic programming courses long ago, and learned some C and C++ on my own, but don't have extensive knowledge.

How I reworked the guide:

• Used Claude.ai (by Anthropic)
• Defined a project in Claude.ai. Permits the user to upload a knowledge base for the AI.
• Uploaded the complete original porting chapter as well as the complete set of Halium Generic Build Tools scripts used for the standalone kernel build.
• Supplied other information relating to what Ubuntu Touch is in order for the AI to refer to information in it's own knowledge base.
• The AI's knowledge cut-off date is April 2024. It does not have direct access to internet, but has an enormous knowledge base from this date.
• Claude.ai is from my own and colleagues' experience way more potent than other AIs we have tried when it comes to coding.

There is no guarantee that what it produces will be correct. Specially not for something like Ubuntu Touch, where an untold amount of what needs to be understood may not be accessible online. However, what is well documented online will generally come out accurately.

The handiwork with AIs, i.e. what makes the difference between a good and a poor result, is largely a question of how you prompt it. You can make it double check and evaluate it's own produced content against specified criteria.

I have done some of this, but probably not enough, seeing as I am working in my spare time, and I generally believe that the lack of sound online documentation specifically targeting Halium and Ubuntu Touch is the main source of errors in the text I have produced.

Conclusion:

• I hope that understanding my background and method will be of use to you when evaluating the contents and that you can help me make this worthy of publishing.
• In my porting efforts, I have frequently needed significantly more assistance and wished for a better understanding than the current guide has been able to offer.
• My goal is to produce something closer to what I have been needing and thereby give the porting effort a serious boost.

[abkro]

I am not sure how to deal with your mermaid - related comment. It is unclear to me whether to leave things as they are, or seek a different solution altogether for displaying this visual? The important thing is for the end users to see it, but without building this locally, of course.

Would removing mermaid-layout-elk.esm.min.mjs solve the issue?

[peat-psuwit]

See, in this situation the ideal solution is to generate the graph image locally at build time using mermaid_output_format config, which is the only way that will work with on-CI preview. But that means fiddling with Jenkinsfile to make sure mermaid-cli is installed, preferably without disturbing the rest of the system.

So if that's too hard to you. The next option is to revert to just let the generated HTML pull the JS files from CDN, which is the situation before I made the first comment. On-CI preview will continue to be broken, but it'll work if you pull the preview from CI and preview locally, and also when it's merged. (This is because apparently support for *_use_local is broken in sphinxcontrib-mermaid, and so probably requires some ugly hack for it to work.)

[abkro]

See, in this situation the ideal solution is to generate the graph image locally at build time using mermaid_output_format config, which is the only way that will work with on-CI preview. But that means fiddling with Jenkinsfile to make sure mermaid-cli is installed, preferably without disturbing the rest of the system.

Did it this way and confirmed locally that this works. I included the Chrome dependencies for good measure, since they turned out to be necessary when I built locally. I placed everything in an adjacent Jenkinsfile.setup-mermaid which I called from the main Jenkinsfile. I hope this looks satisfactory now, @peat-psuwit ?

[abkro]

Well, I can see that this did not work, but this time I don't see any error message detailing the problem, so I'll try to add some debug messages and see what happens.

[abkro]

Finally got this to build properly, so I guess this is ready for you to proceed with the review, @peat-psuwit ?

[abkro]

@peat-psuwit I have addressed the specific points you mentioned, but the remaining one, i.e. your request that I proof read the whole thing better, is something that I really can't do much about, since my knowledge is the limiting factor here. Also, I cannot see any place I can mark this last requested change as addressed, so I guess that's up to you?

I will read through it all, but please understand that beyond things that I have actually tried out myself and properly understood, I don't actually have the necessary knowledge to be able to point out where the text contains factual mistakes.

What I can and will do is to attempt addressing this point as well with AI assistance and see if anything turns up. But this carries the risk of "going in circles", as I am sure you understand.

However, if you can point out additional relevant source material (code) that I can get the AI to analyze in order to better grasp the inner workings of the Ubuntu Touch system, that could be useful.

Lacking something like this, there is no other recourse than for someone who actually has the necessary knowledge to proof read this.

[abkro]

Actually, I have an idea for how to check and adjust the contents. I will close the PR for a bit while I do a some more research and adjustments. I'll reopen it once I have something I think warrants a closer look

[peat-psuwit]

Actually it's better to leave the PR open but mark as draft. See https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft

[abkro]

Ok. Will fix when I get the chance.

[grenudi]

Wow! this is amazing rework ! I can't wait to see it on the web site, as current state of the porting guide is very outdated..