|
| 1 | += Android Project Standards |
| 2 | +include::include.adoc[] |
| 3 | + |
| 4 | +This is a living document. To request changes, please open a pull request. |
| 5 | + |
| 6 | +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL |
| 7 | +NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and |
| 8 | +"OPTIONAL" in this document are to be interpreted as described in |
| 9 | +https://www.ietf.org/rfc/rfc2119.txt[RFC 2119]. |
| 10 | + |
| 11 | += Git |
| 12 | + |
| 13 | +== Location and Naming |
| 14 | + |
| 15 | +The Nerdery SHALL use git, specifically BitBucket Server for all projects unless otherwise |
| 16 | +requested by a client. Projects MUST be placed under the client they are for |
| 17 | +and project names MUST be written in the form of `mobile.{appName}.android` |
| 18 | +(all lower case) or if a library project `mobile.library.android.{libraryName}`. |
| 19 | +For example, the Hy-Vee flagship application is named `mobile.flagship.android`. |
| 20 | +This convention is in place so there is not confusion among the many projects |
| 21 | +that can be listed under a client in BitBucket. |
| 22 | + |
| 23 | +== Branching |
| 24 | + |
| 25 | +Android projects will use git-flow style of branching and merging. Checkout |
| 26 | +https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow[Atlassian's Documentation] |
| 27 | +and this http://nvie.com/posts/a-successful-git-branching-model/[helpful guide] |
| 28 | +for more information. The default branch in Bitbucket MUST be set to develop |
| 29 | +to avoid confusion on which branch to work off of. |
| 30 | + |
| 31 | +To get a feature or hotfix branch merged into the develop branch a pull |
| 32 | +request SHALL be created through the BitBucket UI and be reviewed by at least |
| 33 | +one other developer. The reviewer SHOULD be the lead developer unless the |
| 34 | +lead developer delegates this task out to other team members. Consult with your |
| 35 | +lead for guidance on how they would like the review process to go. |
| 36 | + |
| 37 | +In addition to having a review, the branch MUST pass a merge build from |
| 38 | +<<Continuous Integration>>. This is a build that confirms that the code once |
| 39 | +merged into master will not break the build. |
| 40 | + |
| 41 | +== Forking |
| 42 | + |
| 43 | +Although not required, it is RECOMMENDED to fork repositories under your user |
| 44 | +account. This prevents clutter and reduces the work of figuring out which |
| 45 | +branches can and should be deleted. Under your own fork, you are in charge of |
| 46 | +all the branches and can delete and save them as you see fit. |
| 47 | + |
| 48 | +IMPORTANT: If using a fork you MUST set the 'Repository Permissions' to allow |
| 49 | +the *Production Group* to read. This allows any developer to access and see what |
| 50 | +you are working on. Just in case you forget to create a PR before you go on |
| 51 | +vacation. |
| 52 | + |
| 53 | +== Releases |
| 54 | + |
| 55 | +NOTE: A release is defined as the code that is currently or soon to be in the |
| 56 | +Play Store. |
| 57 | + |
| 58 | +All release builds MUST be tagged. The proper format for a tag would be |
| 59 | +`v{major}.{minor}.{patch}`. |
| 60 | + |
| 61 | +TIP: Don't forget to push the tags to the remote (BitBucket). |
| 62 | + |
| 63 | +An example would be: |
| 64 | +``` |
| 65 | +git tag -a v1.0.0 # -a is not required but RECOMMENDED |
| 66 | +git push origin v1.0.0 |
| 67 | +``` |
| 68 | + |
| 69 | +It is REQUIRED that before creating a release, a release branch is made, |
| 70 | +so that bug fixes can be merged into the release branch while new features can |
| 71 | +be included in master. The release branch name MUST be in the following form, |
| 72 | +`release-{major}.{minor}.{patch}`. The release branch SHOULD be merged into |
| 73 | +`master` once the code has been pushed to the play store. |
| 74 | + |
| 75 | +== Commit History |
| 76 | + |
| 77 | +=== Commit Message |
| 78 | + |
| 79 | +We will follow http://chris.beams.io/posts/git-commit/['The seven rules of a great Git commit message'] |
| 80 | +when creating commit messages. They are as follows. |
| 81 | + |
| 82 | +. Separate subject from body with a blank line |
| 83 | +. Limit the subject line to 50 characters |
| 84 | +. Capitalize the subject line |
| 85 | +. Do not end the subject line with a period |
| 86 | +. Use the imperative mood in the subject line |
| 87 | +. Wrap the body at 72 characters |
| 88 | +. Use the body to explain what and why vs. how |
| 89 | + |
| 90 | +=== Clean History |
| 91 | + |
| 92 | +To keep a clean commit history, which makes reviewing pull requests, and |
| 93 | +rewinding code a easier process, commits on branches SHOULD be complete, |
| 94 | +that is buildable, as well as follow The Seven Rules described above. The RECOMMENDED |
| 95 | +solution to achieve this is to use the `--amend` flag for committing when |
| 96 | +making multiple edits to a branch or where many commits have already been made |
| 97 | +during the development process use rebase command to re-write history. |
| 98 | + |
| 99 | += README |
| 100 | + |
| 101 | +Every project MUST have a README file. The README MUST be a text file, this |
| 102 | +file MAY use a markup language as long as it is easy to read without the use |
| 103 | +of a text processor. For example; plain text (.txt), |
| 104 | +https://confluence.atlassian.com/bitbucketserver/markdown-syntax-guide-776639995.html[markdown] (.md), or |
| 105 | +http://asciidoctor.org/[asciidoctor] (.adoc) would all be fine choices. |
| 106 | + |
| 107 | +The README should contain all information possible about the project. It should |
| 108 | +be the source of truth that will allow a developer to easily find anything |
| 109 | +they need to know about the project. This should include but is not limited to |
| 110 | +links to JIRA, git, Buddy Build, documentation on how to set up the project, |
| 111 | +and how to release the project. |
| 112 | + |
| 113 | +The following README template SHOULD be used for projects. |
| 114 | + |
| 115 | +[README.md] |
| 116 | +``` |
| 117 | +# Project Name |
| 118 | + |
| 119 | +## Important Project links |
| 120 | + |
| 121 | +<!-- |
| 122 | +Place important project links here, anything and everything that is related to |
| 123 | +this project should be documented here. |
| 124 | +--> |
| 125 | + |
| 126 | +- [Project Page](https://mainframe.nerdery.com/project/page) |
| 127 | +- [Source](https://git.nerdery.com/projects/PROJ/repos/cool.project/browse) |
| 128 | +- [JIRA](https://issues.nerdery.com/projects/PROJ/summary) |
| 129 | +- [Bamboo](https://builds.nerderylabs.com/browse/PROJ) |
| 130 | +- [Buddy Build](https://dashboard.buddybuild.com/apps/1e5f9410f32f459aa9c3ca72a52cf6c1) |
| 131 | +- [Fabric](https://fabric.io/android/apps/cool.project/) |
| 132 | +- [Firebase](https://console.firebase.google.com/project/cool-project/overview) |
| 133 | +- [Play Store](https://play.google.com/store/apps/details?id=cool.project.android) |
| 134 | +- [Notes and Wires](https://drive.google.com/drive/u/1/folders/0B5j3shyAKaAnRks4b1hNY2kxWUE) |
| 135 | + |
| 136 | +## Build Types |
| 137 | +<!-- |
| 138 | +Give each build variant/flavor a different section here. Explain what each |
| 139 | +does, why one would use it, what features each has, links to associated |
| 140 | +services (ie. crashlytics, firebase), which should be given to clients, and what |
| 141 | +signing keys are used. |
| 142 | +--> |
| 143 | + |
| 144 | +## Project Setup |
| 145 | +<!-- |
| 146 | +Describe step by step setup and any dependencies that are required and |
| 147 | +their setup as well. |
| 148 | +--> |
| 149 | + |
| 150 | +## In Scope Devices |
| 151 | +<!-- |
| 152 | +List out devices that are in scope here. |
| 153 | +--> |
| 154 | + |
| 155 | +## Contributing |
| 156 | +<!-- |
| 157 | +Include any special requirements for contributing to the project. Are there |
| 158 | +special style guides that must be followed? Is there a different flow for |
| 159 | +doing pull requests. Anything else that might be relevant for contributing. |
| 160 | +--> |
| 161 | +``` |
| 162 | + |
| 163 | +NOTE: The above is a guideline for creating a good README, but anything that |
| 164 | +is thought to be useful in a README should be included. Anything about a project |
| 165 | +that differs from standard operating procedure SHOULD be documented in the |
| 166 | +README. |
| 167 | + |
| 168 | += Testing |
| 169 | + |
| 170 | +== Unit Testing |
| 171 | + |
| 172 | +Unit Tests SHOULD be implemented for all code that does not have direct dependencies |
| 173 | +on `android` packages and does some amount of work. That is any code |
| 174 | +that is not in the views, fragments or activities, should be tested. |
| 175 | +Not having the time to unit test is not a valid excuse for not testing. Time |
| 176 | +is always saved in the long run when testing. |
| 177 | + |
| 178 | +== UI Tests / Functional / Instrumentation Tests |
| 179 | + |
| 180 | +All of these types of testing are RECOMMENDED, but should be considered on a |
| 181 | +case by case basis to see if they fit for the project. |
| 182 | + |
| 183 | += Continuous Integration |
| 184 | + |
| 185 | +All Android Projects at The Nerdery MUST use CI. |
| 186 | +https://dashboard.buddybuild.com[Buddybuild] is a quick and |
| 187 | +convenient way to set this up with our BitBucket Server. |
| 188 | + |
| 189 | +== Setting Up Buddybuild |
| 190 | + |
| 191 | +. Create a ticket to http://nrdry.com/sisreq[SIS] to allow |
| 192 | +Buddybuild to see your project. Buddybuild |
| 193 | +can not see projects by default to ensure our client's privacy. Projects with |
| 194 | +specific security requirements may not be able to use Buddybuild. Check |
| 195 | +with your project lead or project manager to ensure that you may use Buddybuild. |
| 196 | +. While you are waiting for your project to be exposed to Buddybuild follow |
| 197 | +these directions to get your |
| 198 | +http://docs.buddybuild.com/docs/connect-with-bitbucket-server[BitBucket Account integrated] |
| 199 | +with Buddybuild. |
| 200 | +. Once your project is visible to Buddybuild, follow |
| 201 | +http://docs.buddybuild.com/docs/selecting-an-app[these steps] to get |
| 202 | +your project setup and building. |
| 203 | + |
| 204 | +NOTE: It is RECOMMENDED to let Buddybuild handle the building of your release |
| 205 | +APKs and managing version numbers. This avoids confusion and ensures a single |
| 206 | +place where every build will be built in the exact same way. |
| 207 | + |
| 208 | += Logging |
| 209 | + |
| 210 | +Logging is very important in be able to quickly debug applications. For this |
| 211 | +the reason The Nerdery Android Developers have adopted |
| 212 | +https://github.com/JakeWharton/timber[Timber] as the logger of choice. |
| 213 | +Timber allows to quickly log values to different streams instead of just logcat. |
| 214 | +Timber also allows for the type of logging to be easily switched from build |
| 215 | +type to build type. |
| 216 | + |
| 217 | +The Nerdery SHOULD use Timber in all new projects and is RECOMMENDED to be used |
| 218 | +in legacy projects when the legacy project does not have a logging alternative |
| 219 | +to logcat. |
| 220 | + |
| 221 | +Release builds MUST NOT log to logcat. This is a security concern as well as a |
| 222 | +performance issue. Logs SHOULD instead be sent to Crashlytics, Google Analytics, |
| 223 | +Firebase, Loggy, or some other comparable cloud logging option where they can |
| 224 | +be reviewed and used to debug issues. |
0 commit comments