-
Notifications
You must be signed in to change notification settings - Fork 0
Contributions
Android Architecture Blueprints is an open-source project curated by Google.
We're happy to accept contributions in the form of new samples, bug fixes, issues, and documentation fixes. If you want to help out, add a comment on the issue you want to work on and hack away! Before starting work on an app intended for submission, please open an issue to discuss it with the team. This will allow us to review the framework being used to determine if a spec-compatible app is likely to be accepted.
Blueprints is a curation, not a collection. This is why we can't accept every submission. There are mainly two categories of samples:
- Architectural patterns: Model-View-Presenter, Model-View-ViewModel, Model-View-Controller and other paradigms that determine each component's responsibility.
- Architectural tools: Dependency injection frameworks, data binding and loading libraries, languages, etc.
A sample will generally be a combination of patterns and tools.
We want to make it easier for developers to find an architecture for their apps, not harder. This is why it's very important to maintain consistency between projects to simplify comparing code as much as possible. Keep diffs small by keeping an eye on:
- Code style
- Directory structure and non-source files
- UI tests
Please check out the Code Style for Contributors section in AOSP.
In general, directories and packages should be able to tell what an app does and make it easy to find the different features and components. Keep consistency with the existing apps and only make changes to the directory structure if the sample requires it.
Apply the same criteria to files like the Android manifest, gradle files, resources, flavors, etc.
UI tests serve an important role in this project as it's a requirement that they all pass without modification. All samples have the same UI tests so any modification to them must be done across all samples.
Unit tests must cover a sensible percentage of code. Testability is one of the main metrics used to compare projects so in order to keep consistency, please use the following criteria:
- Unit-test your business logic.
- Do not create integration tests between your business logic and the framework or libraries. Do not use testing frameworks like Robolectric.
- Use JUnit4, Mockito, Hamcrest, Mockable Android Jar.
- Do not use powermock/powermockito unless refactoring would impact performance or readability.
Example: TasksPresenterTest.java.
Unit tests on device can be used to check business logic tightly coupled with the framework, like a SQLite-based data source that would benefit from testing against different API levels and devices.
Example: TasksLocalDataSourceTest.java.
All samples have a flavor dimension used to switch between real and mock data: prod and mock. Both mock and prod UI test must pass. Some tests can be restricted to the mock flavor by moving them to the androidTestMock directory.
UI tests are a meta-project that require a lot of maintenance so pull requests against them are encouraged.
Run compare_tests.sh to check that all Android tests match. Add -v to show a diff between files.
Screen tests will test all possible situations and user actions on each screen. Consider it a UI unit test.
Example: StatisticsScreenTest.java
UI end-to-end tests check user flows.
Example: TasksScreenTest.java
Each sample will have an individual or a group listed as author. Authors are asked to review PRs, consider issues and ideas related to the sample.
Samples will likely require some maintenance and community work, like keeping the dependencies up-to-date and responding to issues and reviewing PRs.
Common dependencies like build-related, *Compat libraries, Espresso, Hamcrest, etc. will be bumped periodically by core maintainers across all samples.
A sample may be marked as deprecated and removed from the codebase if it's no longer of use to the community (eg. using an unmaintained or deprecated tool).
Do not use the master branch for development or pull requests. Each sample has its own development branch so that fixes in a sample can be merged into others easily. Read this page about Development branches.
There must be at least a README.md file in the project's top-level directory with, at least, the following sections:
What is this sample showcasing and what other sample it is based on, if any.
Explain why this sample is different to every other sample.
If this sample cuts corners for the sake of readability or simplicity or it has any //TODOs, list them here.