Brave Heart 'welcome letter' draft - feedback welcome

[Luke]

Hi everyone,

I drafted a Brave Heart welcome letter and would appreciate your feedback. Is something missing? should something be phrased differently? Let me know.

[edit] I redrafted the letter based on your suggestions. Tried to squeeze as much as I could in the little space a page permits. Feedback please - don't have much time to get this to TL.

Dear Piner,

Congratulations on receiving your Brave Heart edition PinePhone! 

You are one of the very first to have a PinePhone and we hope you’ll help us and our partner projects by testing, contributing to, and documenting the development progress. Thank you!

Brave Heart phones come preloaded with a factory test software and nothing else, so you’ll have to seek out the OSs you’re interested in on your own. Most mobile distributions OS images are linked on the PinePhone subsection of the PINE64 Wiki (wiki.pine64.org). 

The PinePhone Wiki subsection also contains schematics, instructions, hardware configuration details and other useful information about your device. You can edit and contribute to the Wiki by logging in using your forum credentials. We encourage you to do so.  

Since this is fundamentally a community project, we strongly suggest you join the #pinephone chat, accessible via Telegram, Discord, IRC and Matrix (NB. all chat protocols are bridged). You can find links to the chat on PINE64 Wiki and under the Forums and Chats tab our main site (pine64.org). Your input is valuable regardless of if you’re a tester, developer or just an enthusiastic end-user, so it is important that you join the conversation.

Most partner projects - a list of which can be found under Partner Project tab on our site - also have discussion threads or chats dedicated to the PinePhone. So if you’re interested in one particular OS, and wish to contribute to it, then make sure to check out the forums and/or chats of the project in question.  

Brave Heart is meant for early-adopters - developers and enthusiasts - so we expect and even encourage you to experiment with the software and hardware by pushing the envelope. That said, please keep in mind that the device is under standard warranty, so braking components during disassembly or tampering with eFUSEs is a subject to voiding of your warranty. We trust this is common sense. 

Now, have fun with your PinePhone!  

PINE64 Community Team

Redraft:

Dear Piner,

Congratulations on receiving your Brave Heart edition PinePhone! 

You are one of the very first to have a PinePhone and we hope you’ll help us and our partner projects by testing, contributing to, and documenting the development progress. Keep in mind that all OSs are presently in a pre-release (Alpha) state and vary in functionality, even from one pre-release to another.   

Your input is valuable so it is important that you report problems you encounter and join the conversation on whatever platform suits you best. When you report problems make sure to also include relevant logs and/or UART outputs. 

You can report non-OS specific (kernel) issues you encounter on: https://gitlab.com/pine64-org. OS specific problems should be reported on the PINE64 Wiki (wiki.pine64.org/PinePhone#Software Support) as well as directly to developers in the pinephone chats (Forums and Chats tab on https://pine64.org), on PINE64 forums (forum.pine64.org) or on the relevant partner-project forums (see Partner Projects tab on https://pine64.org). 

Brave Heart phones come preloaded with a factory test software and nothing else, so you’ll have to seek out the OSs you’re interested in on your own. Most mobile distributions OS images are linked on the PinePhone subsection of the PINE64 Wiki. OS builds absent from Wiki may require you seek them out by talking to developers directly.

The PinePhone Wiki subsection also contains schematics, instructions, hardware configuration details and other useful information about your device. You can edit and contribute to the Wiki by logging in using your forum credentials. We encourage you to do so.  

Brave Heart is meant for early-adopters - developers and enthusiasts - so we expect and even encourage you to experiment with the software and hardware by pushing the envelope. That said, please keep in mind that the device is under standard warranty, so braking components during disassembly or tampering with eFUSEs is a subject to voiding of your warranty. We trust this is common sense. 

Now, have fun with your PinePhone!  

PINE64 Community Team

[dukla2000]

Hey Lukasz, more exciting is when the letter has to be ready by?!

2 suggestions, the first is easy - to reword the last para as follows:

Brave Heart is meant for early adopters, developers and enthusiasts, so we expect and even encourage you to experiment with the software and hardware by pushing the envelope. That said please keep in mind that the device is under standard warranty, so breaking components during disassembly or tampering with eFUSEs etc will void your warranty. We trust this is common sense.

The second is more a question of intent: both your letter (and the wiki Main page) emphasize the chat platforms and minimise this forum. I think they both have a place and so the forum needs a boost in emphasis: chat for immediate stuff and possible immediate access to developers, forums for asynchronous logging and to leave a better searchable trail for those who follow. Similarly there is an opportunity to (try) influence the process of discovery/reporting of defects: I figure the partner projects are likely to get overwhelmed by a large volume of new users and so the wiki was a good place to document reporting preferences for each partner. "FlyingToast" removed my draft attempts to cover this in the wiki and doesn't respond to forum PM. I realize that is a pseudonym for a more active chat member but have not got the translation so this may in fact be Pine64 preference?

Perhaps your prioritisation of the chat platform is deliberate (for all issues) in which case ignore this ramble!

[Luke]

Thanks @dukla2000 !

The letter needs to be done fairly soon - within a few days. I'll reword as per your suggestion.

About the forums, chats, reporting bugs and issues, etc. Its actually even more complex in the particular case of the PinePhone, since I expect most issues will be related to OSs which are all built by partner projects who have their own forums. To my knowledge relatively few PinePhone devs check into the PINE64 forums, opting to use their own or the chats, but I may be wrong about this. I'll think more on this - good points all around.

I too think that wiki should get some love and should be utilised for this project particularly much. About FlyingToast - I'm not sure who the person is - PM me about about the situation please - I am not aware of this.

[undo]

I don't know if it is in the scope of this letter (probably not) but I would just like to have a general "best practice" recommendations for reporting on any issues that are found. I have never been involved in any development or reported bugs as a user, but it seems to me like the people who are developing software take their channels for granted while to an outsider like myself it is not transparent. Could someone draw a flow chart as to how a bug of a certain kind should be processed through the different channels (chats, forums, wiki) ? Or, if someone will clarify the process to me, I can draw a chart.

---

Oh, and I would add that there should be some guidelines and how-to for bug reporting. People always say "give us logs" but is there a list of all the possible logs somewhere? I find it confusing. I don't know what log is relevant.

---

By the way I appreciate the term "piner" for it's tone. It's almost taoist.

[Dmytro]

Hey @Luke,

may be, considering it's going to happen early next year, it could be more prizing and congratulating
Some "pathos" as we can read it on big pine events here would be nice as well (imho).
Kinda:
"YOU are the very brave piner..."
"Your mission should you choose to accept it would be to develop..."
"True Piner like YOU can do this all day!"
"...let the Pine be with you!"

[Luke]

@undo yea, the thing is - I honestly don't know where the different project devs want issues reported. Perhaps listing the 'common' gitlab is both a safe and reasonable option. I'll include that.

@Dmytro haha, yes, problem is that not everyone is a native speaker and can understand the lighthearted allusion That said I too think that the letter should have an encouraging nad lighthearted tone overall

[undo]

I guess if it is reasonable to have a wiki page about bug reports, you could link that page in the letter, even if it didn't have much content yet?

---

Knowing that it is linked would give the community incentive to keep it up to date.

[wibble]

It would be good to have some pointers to how the whole ecosystem fits together for those new to, or out of touch with, the linux-on-a-phone thing. Bits like ofono (which isn't listed as a partner project) will be used by most if not all the OS flavours, and I guess there will be other shared areas where a little work might benefit everyone. This is probably a better fit for the wiki than the letter though.

[dukla2000]

To my knowledge relatively few PinePhone devs check into the PINE64 forums, opting to use their own or the chats, but I may be wrong about this. I'll think more on this - good points all around. 

I don't know if it is in the scope of this letter (probably not) but I would just like to have a general "best practice" recommendations for reporting on any issues that are found. I have never been involved in any development or reported bugs as a user, but it seems to me like the people who are developing software take their channels for granted while to an outsider like myself it is not transparent. Could someone draw  a flow chart as to how a bug of a certain kind should be processed through the different channels (chats, forums, wiki) ? Or, if someone will clarify the process to me, I can draw a chart.

---

Oh, and I would add that there should be some guidelines and how-to for bug reporting. People always say "give us logs" but is there a list of all the possible logs somewhere? I find it confusing. I don't know what log is relevant.

---

It would be good to have some pointers to how the whole ecosystem fits together for those new to, or out of touch with, the linux-on-a-phone thing. Bits like ofono (which isn't listed as a partner project) will be used by most if not all the OS flavours, and I guess there will be other shared areas where a little work might benefit everyone. This is probably a better fit for the wiki than the letter though.

My vote for a wiki page to cover all/any releases, especially during this Brave heart phase, is here.

The main intent is to have specific links to the places where each Partner best wants to hear feedback. And good point @undo - to also specify what they want in  any such feedback.

[wood]

I think the wording is very good, but considering some other responses here, perhaps you should make a more detailed statement about the relationship between pine64 and the different OS projects and how that will complicate reporting of problems and other user responses.

I believe the pinephone is the first consumer-oriented phone that has ever been released without the "full stack" being controlled and distributed by the device manufacturer.  It is going to be a challenge to keep track of what issues involve the hardware itself and what issues are related to the OS project.  Add to this the fact that each OS project has its own policies, communication methods, and culture and you have a recipe for confusion for the end user.  For example, as a user if I try to run postmarket and can't connect to my wifi is the problem that I haven't configured the connection right (my problem), a network stack issue (a project-level problem), or bad hardware (a pine64-level problem)?  

This isn't a bad thing, as long as everyone has a firm grasp of the distributed nature of the effort.  You have done a wonderful job of communication; the "Brave Heart" approach is probably the best way to ease this transition, but I still worry about how "we" (non-developer brave heart early adopters) will end up fitting into the different project communities that have been built by the developers (a very different culture).

I'm hoping that each project has thought through this (I'm guessing some of them are secretly dreading the assault of non-technical users on their solution-focused communities).  Perhaps Pine64 can help coordinate a more user-friendly set of "launching points" for each project.  You have the framework in place both on the pinephone wiki page and the software forum.  Maybe you could ask each project for more detailed "getting started" info for early adopters, especially an description of how each community prefers to handle communication.  Those writeups would be added to the wiki and forums entries as "getting started with" guides that introduce the community as well as just the steps to install and boot the device for the first time.   Sort of a "welcome letter" for each project?