mozilla-mobile / shared-docs Goto Github PK

Right now they're hosted in fire tv: https://github.com/mozilla-mobile/firefox-tv/wiki/Crash-reporting-with-Sentry and focus: https://github.com/mozilla-mobile/focus-android/wiki/Crash-Reporting-with-Sentry

• How does the process work (this changes soon though!)
• How to add and update strings (Especially mention: change ID of string!!)
• ..

Include notes on how to search. There's the:

• GDrive
• github pages site

searchfox & friends.

Very often is is a good workflow to work on a component while you have embedded that component in an end user application.

For example say you are making UI changes in the toolbar. It is convenient to check out both Focus and Android-Components and see your changes in the toolbar component reflect when you run and debug Focus. Without having to use them as separate projects and depend on jar dependencies.

If this is possible, let's document how to set this up.

Like https://github.com/mozilla-mobile/focus-android/wiki - it's pretty cool.

A wrote this at one point:

While you can use commits for yourself, a commit series in a pull request is for the reviewer (or the bisector): they should tell a story which helps the reviewer understand the code. A good story should be modular and shouldn't go back on what it has already said.

For example, a good story says "I put down this building block and this building block so I can place another building block on top of both them, which makes it easier to fit this building block, and the final building block on top of that, which completes the issue." However, this story feels like, "I put down this building block, then picked it up and moved it back here, then added another building block, which I moved forward an inch, ..."

Prefer talking in channel over DM because:

• Other people's expertise can help
• Someone can answer if the person you ping is not around

Kotlin weekly, Android weekly, Android developers blog, etc.

To answer questions like:

• Who's who on the team? What are their roles?
• Who should I ask questions to?

Users can currently find core committer information via version control and suggested reviewers but they don't know their areas of expertise. They don't know who is on the UX/product/QA teams. This affects onboarding new hires as well as contributors.

My hesitation in adding this documentation is:

• It's easy to go out of date
• It could be too personal

Other projects include the core contributors in an AUTHORS file (as opposed to a CONTRIBUTORS file).

• Docs of the telemetry we record
• Where to find the data
• Where to look in the code to add data
• Link to telemetry libs

Sometimes we get developers interested in contributing who do not have experience using git or github yet. It would be great to have a document explaining (or linking to good guides) how to fork a project, how to keep a local copy up to date, how to commit / amend / rebase / push and how to open a pull request and update it after review.

• Test naming conventions
• UI vs integration vs unit: when to write which?
• androidTest package hierarchy
• robot pattern

• install
• uninstall
• force stop
• start Activity
  etc.

Like https://github.com/mozilla-mobile/focus-android/wiki/Architecture-Decisions via http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions

We can add an ADR for this repo:

• Why a shared repo?
• Why document in files rather than wiki

See our internal discussion for opinions: https://groups.google.com/a/mozilla.com/forum/#!searchin/mobile-all/beginning$20android%7Csort:date/mobile-all/DqfIA88gyFM/RCgLjPXbAwAJ

This may not be necessary given how much AS does but it'd be nice to teach users how to self-service themselves, e.g. ./gradlew tasks to find relevant tasks and run them, difference between assemble/build, etc.

e.g.

Fork

To fork...

Branch

To branch...

Pull Request

...

This will help us make it more beginner friendly, I think. Hopefully it doesn't make it too difficult for experienced devs (it might improve it because the irrelevant information is out of the way).

Add a section about licenses.

Over in the application-services repo we have some notes on how to get your apks signed via autograph:

https://github.com/mozilla/application-services/blob/91a10d8/docs/howtos/signing-android-applications.md

This is very specific to building an android app, and feels out of place with the other documentation in that repo. Would you be interested in merging some or all of that content over to an appropriate doc in this android-specific repo instead?

I'm happy to do the legwork if you can give me some pointers on whether and how it would best fit in with the material that's already here.

Address comments in #1 like:

We should update this to mention versioning the image. That's what we do in android-components and it prevents overriding a working image with a broken one and subsequently breaking all automation tasks. Of course we do not need to do that now and could also just file an issue here..

In a nutshell:

# Tag the created image with a version number:
docker tag mozillamobile/focus-android:latest mozillamobile/focus-android:1.0

# Then push both tags
docker push mozillamobile/focus-android:latest
docker push mozillamobile/focus-android:1.0

# In the .taskcluster.yml make sure to specific the image with the version number. With that you can test a new image in a PR before using it for all other tasks.

and

Same here. For versioned images:

docker pull mozillamobile/focus-android:1.0

How we use milestones, plan, our labels, etc. This is currently documented in focus: https://github.com/mozilla-mobile/focus-android/wiki/Sprint-Process

All marked reviewers should generally review; all PRs should have a reviewer specified before being reviewed. If there is no reviewer specified, someone should specify a reviewer (themselves or otherwise).

Also, turn-around time expectations? Maybe not to avoid mismatched expectations in crunch time.

How to handle notifications: e.g. I use email and have two mail filters:

• Github (content matches: mentioned, assigned, requested, or authored)
• Github/uninvolved (everything else)

Adding a dark mode as effective as Samsung Internet's or even better is something I find very convenient and less eye straining. I would like this to be built into the browser other than having to use an extension as this makes it harder for me to move over to Firefox on mobile

e.g. how to use:

• fonts
• colors

We probably don't need the basics but we should inform people to:

• Install instant run platform
• Don't upgrade gradle plugin

Bonus:

• File headers plugin
• Markdown plugin
• How to take screenshots/video recordings

Based on our telemetry of real versions seen in the wild, maybe?

It's really sparse right now and maybe we'd have more people interested if it was more verbose. We can describe how SUMO works, e.g. articles and forums, and what contribution looks like.

• How to use remote debugging (since we use WebViews)
• Which add-ons to install to make GitHub better ;)
• pre-push hooks
• How to check out pull requests
• ag
• Dash
  etc.

https://github.com/mozilla-mobile/focus-android/wiki/Feature-&-Issue-workflow

This is a to-the-point version about how we fork, expect pull requests, etc. Maybe even a PR checklist.

This should not include how-to-learn basic git documentation: that's #3. They could be in the same document, however.

• File license headers
• Give it more memory (for memory profiler)
• newline at end of file
• No wildcard imports
• ...?

How much of this can be done with a shared style file though? (Colin mentioned this in my PR for kotlin style guide)

Currently in our internal onboarding doc.

Dependencies, copying code, licensing, etc.

Also how to work in our project, e.g. should put MPL header on top of every file.

(Let's do this after migrating to the new system)

We should document how we use strings, how they get translated and what features we support.

As of January 1 2019, Mozilla requires that all GitHub projects include this CODE_OF_CONDUCT.md file in the project root. The file has two parts:

1. Required Text - All text under the headings Community Participation Guidelines and How to Report, are required, and should not be altered.
2. Optional Text - The Project Specific Etiquette heading provides a space to speak more specifically about ways people can work effectively and inclusively together. Some examples of those can be found on the Firefox Debugger project, and Common Voice. (The optional part is commented out in the raw template file, and will not be visible until you modify and uncomment that part.)

If you have any questions about this file, or Code of Conduct policies and procedures, please see Mozilla-GitHub-Standards or email [email protected].

(Message COC001)

e.g. developer newsletter

What's:

• A nit?
• r+
• r+ w/ nits?
• lgtm
• Our continuous integration? How do you find test failures?

just in case anybody runs into this same problem, i was seeing the gradle task
testAmazonWebviewDebugUnitTest
hang after throwing an
InvocationTargetException
turns out there's some issue when using Jacoco with newer JDK versions. downgrading from java 10 to 8 fixed the problem

People opening PRs can't get automatic reviewers - setting an automatic reviewer will at least put it on someone's specific radar.

https://help.github.com/articles/about-codeowners/

I saw some cool pages today:

• https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/How_the_Web_works
• https://developer.mozilla.org/en-US/docs/Learn/Common_questions/How_does_the_Internet_work
• https://www.html5rocks.com/en/tutorials/internals/howbrowserswork/

But also maybe good HTML/CSS/JS learning resources.

via #48 (comment):

I think we should create a living Mozilla style guide,

I agree: it would be good to document how we use things that aren't explicitly documented elsewhere or not enforced by our tools (I wish the tools were stricter!).

With a note on how to learn coroutines. See internal discussion: https://groups.google.com/a/mozilla.com/forum/#!searchin/mobile-all/beginning$20android%7Csort:date/mobile-all/DqfIA88gyFM/RCgLjPXbAwAJ