├── Contributing_code.md ├── Gerrit_rules.md ├── License_template.md ├── Porting_Omni_To_Your_Device.md ├── README.md └── images ├── Omnirom_logo-big_layout_transparent-300px.png ├── Omnirom_logo-big_layout_transparent.png ├── Topic_gerrit_rules.png └── omnirom_logo-big_layout_transparent-250px-150x150.png /Contributing_code.md: -------------------------------------------------------------------------------- 1 | ![LOGO](images/omnirom_logo-big_layout_transparent-250px-150x150.png) 2 | # OmniROM Documents 3 | ## Contributing code to Omnirom 4 | 5 | ### Creating a patch 6 | 7 | The beauty of open source projects is the ability for even the most novice of developers to be involved in determining the trajectory of the project. The difficulty is in knowing exactly how to submit your patch for code review and (hopefully) inclusion into the project. 8 | 9 | Below are the simple, basic steps for contributing code: 10 | 11 | 1. Begin by performing a `repo sync` so that we know we’re dealing with the most recent versions of the code. We're also assuming that you have experience with terminal & you have your OmniROM repo in ~/android/omni: 12 | ``` 13 | #: cd ~/android/omni 14 | #: repo sync 15 | ``` 16 | 2. Go to https://gerrit.omnirom.org and register. ***Make sure to accept the agreement.*** 17 | 3. Now go and make the changes to the files you are wanting to change. 18 | 4. Now in terminal, navigate to the project directory. 19 | 5. We need to commit the changes to gerrit for review, along with a message telling exactly what was done for the reviewer(s) to review 20 | 6. Let's check what all we changed 21 | ``` 22 | #: git status (''this will tell you the files that were changed'') 23 | ``` 24 | 7. Now let's add the files 25 | ``` 26 | #: git add 27 | ``` 28 | if you need only some of the changed files, or use 29 | ``` 30 | #: git add -A 31 | ``` 32 | to add all the files. 33 | 8. Now we need to create a commit for the changes 34 | ``` 35 | #: git commit 36 | ``` 37 | This will open up an editor and at the top line you will need to provide the comment about the changes you have done. 38 | - Suggested format: 39 | ``` 40 | : 41 | ``` 42 | - Example: 43 | ``` 44 | Base: Add new ringtone 45 | ``` 46 | 9. Once done press CTRL-O to save your changes, and then CTRL-X to exit. Your changes will be saved, and you’ll receive a notice about the number of changes to be submitted. 47 | 10. Now we need to upload our changes to gerrit for review. 48 | ``` 49 | #: git push ssh://@gerrit.omnirom.org:29418/ HEAD:refs/for/ 50 | ``` 51 | - Example: 52 | ``` 53 | git push ssh://UtkarshGupta@gerrit.omnirom.org:29418/android_frameworks_base HEAD:refs/for/android-7.1 54 | ``` 55 | 11. This will upload the changes, and you’ll receive a web link to those changes like https://gerrit.omnirom.org/1479/ 56 | 57 | **For more information on Gerrit, see [Gerrit Rules](Gerrit_rules.md).** 58 | 59 | ### Creating a patchset 60 | Now that you have created a patch, you may want to change it. To create a patchset, follow the below steps: 61 | 62 | 1. Begin by performing a `repo sync` so that we know we’re dealing with the most recent versions of the code. We're also assuming that you have your Omnirom repo in ~/android/omni: 63 | ``` 64 | #: cd ~/android/omni 65 | #: repo sync 66 | ``` 67 | 2. Now in terminal, navigate to the project directory. 68 | 3. Cherry-pick your patch from gerrit. 69 | 4. Make your changes 70 | 5. Now let's change our original commit 71 | - Let's check what all we changed: 72 | ``` 73 | #: git status 74 | ``` 75 | this will tell you the files that were changed 76 | - Now let's add the files: 77 | ``` 78 | #: git add 79 | ``` 80 | if you need only some of the changed files, or use 81 | ``` 82 | #: git commit -A 83 | ``` 84 | to add all the files. 85 | - We want to change our original commit instead of creating a new one 86 | ``` 87 | #: git commit --amend 88 | ``` 89 | This will open up the same editor we dealt with already. 90 | - Make any changes to the commit message that you need to and exit, making sure to save your changes. 91 | 6. Now the commit is ready to be pushed. This will edit the original commit instead of creating a new one. 92 | 93 | ### Getting lazy 94 | Typing `git push ssh://@gerrit.omnirom.org:29418/ HEAD:refs/for/` every time is a painful job. So instead of typing it every time, we can create a remote for it: 95 | ``` 96 | #: git remote add ssh://@gerrit.omnirom.org:29418/ 97 | ``` 98 | Using it 99 | ``` 100 | #: git push HEAD:refs/for/ 101 | ``` 102 | You'll have to create remotes for every project, but hey - you're getting lazy. 103 | 104 | #### Getting more lazy 105 | If you're *extremely* lazy, you can install **git-review** via [this guide](http://www.mediawiki.org/wiki/Gerrit/git-review). Once done, you will need to configure it: 106 | ``` 107 | #: git remote add gerrit ssh://@gerrit.omnirom.org:29418/ 108 | #: git review -s 109 | ``` 110 | 111 | ***Creating a patch:*** 112 | ``` 113 | $ git checkout -b mycoolfeature 114 | ``` 115 | Change the files you need to, then: 116 | ``` 117 | $ git commit -a 118 | $ git review 119 | ``` 120 | 121 | ***Creating a patchset:*** 122 | ``` 123 | $ git checkout mycoolfeature 124 | ``` 125 | Change the files you need to, then: 126 | ``` 127 | $ git commit -a --amend 128 | $ git review 129 | ``` 130 | 131 | ### Licensing 132 | 133 | It is important that any code you contribute follows either the existing licensing, or utilizes the correct licensing. For pre-created headers, see the [License template](License_template.md). 134 | -------------------------------------------------------------------------------- /Gerrit_rules.md: -------------------------------------------------------------------------------- 1 | ![LOGO](images/omnirom_logo-big_layout_transparent-250px-150x150.png) 2 | # OmniROM Documents 3 | ## Gerrit rules 4 | ### Submitting a patch 5 | 6 | #### The contents of your patch 7 | You should make sure you use different repo branches for your patch, to ensure you don’t have an unneeded dependency on another patch. Use `repo start` for every new changeset you make, and `repo checkout` to switch between your changes. For more on **repo** and **git** see [Using repo and git](Using_repo_and_git.md). 8 | 9 | Your code should contain only the required changes to make your feature work. You should remove all unneeded comments (debug, commented code) and code (unneeded debug log commands, etc). Make sure your code style sticks to the [Android Guidelines](https://developer.android.com/training/index.html), and that you don’t have trailing spaces (spaces at the end of a line). 10 | 11 | #### Work-in-progress 12 | Commits that are work-in-progress may bypass the above paragraph, but must be clearly marked with a **[WIP]** tag at the very beginning of the commit message. This way they won’t be auto-tested by our verification bot, and testers will know your patch isn’t ready for prime time yet. 13 | 14 | #### Formatting your commit message 15 | The first line of your commit message should be a swift summary of your change, that should make your patch recognizable easily on Gerrit’s patch list. Think of it as a patch title. 16 | 17 | ***Good:*** 18 | - surfaceflinger: Add compatibility support for MTK 19 | - liblights: Fix keys not lighting up on i9300 20 | - telephony: Enhance the way CDMA is operated 21 | 22 | ***Bad:*** 23 | - MTK support 24 | - ……!!!!!!! 25 | - Add class1, class2, backwards compatibility, support layer and gralloc changes to make MTK chipsets (6589, 6582) working with Android 4.3 26 | 27 | The lines following your "title" should contain a deeper explanation of what your commit changes (e.g. with answers to ‘why’ and ‘how’ for your patch). Indicating changes between different Patch Sets might be a good idea. It is possible however to give details in the comments section instead. 28 | 29 | ### Cherry-picks from other sources 30 | In case you’re cherry-picking a patch from a trustable upstream source (the Linux kernel, AOSP, etc.), you should not change the commit message, so that we can recognize upstream patches more easily, and keep history clean. Comments should be done in the Gerrit ticket’s comment section, not in the commit message. 31 | 32 | In addition, preserve authorship of your cherry-pick, do not change the authorship to yourself. Authorship should automatically be preserved if you perform a `git cherry-pick` or use `git am` to apply a git-formatted patch. 33 | 34 | #### Multi-project changes 35 | 36 | In some cases, one feature might affect multiple projects (repositories) at once, in a way that you need to upload multiple Gerrit review tickets. In such case, your changes should follow the following naming convention: 37 | ``` 38 | [1/2] xxx: yyyyyyyyyyyyyyyyy 39 | ``` 40 | ``` 41 | [2/2] xxx: yyyyyyyyyyyyyyyyy 42 | ``` 43 | As we have an automated system testing patches, you must follow that naming convention properly, and affect the same topic name to the patches going together: 44 | 45 | ![gerritRules](images/Topic_gerrit_rules.png) 46 | 47 | ### Getting Your Patch Validated 48 | Our review process is totally open, but a few conditions may apply. In order to get your patch approved, you must ensure that: 49 | 50 | - Your patch builds with a clean tree (and the dependencies, if any) 51 | - Your patch follows all of the above rules 52 | - Your patch isn’t against the laws (e.g. confidential material) 53 | - Your patch isn’t a troll, and has an actual reason to exist 54 | 55 | All users on Gerrit are then able to **+1**, or **-1** your patch. In case your patch introduces a big change, or if you need UI/UX/Concept feedback, we encourage you to open a ticket on [Omni’s JIRA](http://jira.omnirom.org/) in the UI Review or Concept Review projects. 56 | 57 | ### Signaling your patch is ready for review 58 | 59 | In order to signal to potential reviewers that your patch is ready for review, you need to do a review of your own change and set it “**Code-Review: +1**”. This tells potential reviewers that the author has deemed it ready to be reviewed and allows changes to stay on gerrit while they are refined. Similarly, if you feel your patch isn’t ready, setting Code-Review to -1 immediately tells people to not bother looking at it yet. 60 | 61 | Once the patch is signaled ready for review, it will be automatically tested by the Omni Build Verifier, which will give a Verify: +1 or -1 depending on whether your changes build successfully. 62 | 63 | ### Override of the open review process 64 | There might be cases where an open review process can go wrong, or must be bypassed for a few reasons. Patches will be rejected or put on hold if: 65 | 66 | - They introduce an obvious security hole 67 | - They are trolls 68 | - They don’t follow these guidelines and the previous rules 69 | - They cause a massive amount of discussion between users (in this case, the discussion will be put down in another place where it can be discussed more easily). 70 | 71 | Patches can be submitted without prior deep review if: 72 | 73 | - They fix an important system-wide security hole 74 | - They fix a valid legal issue (e.g. licensing) 75 | - They fix an important system bug, or build breakage. 76 | 77 | ### Allowing merge commits 78 | 79 | See https://code.google.com/p/gerrit/issues/detail?id=1072 if you have issues getting merge commit permissions to work in comment 6. 80 | -------------------------------------------------------------------------------- /License_template.md: -------------------------------------------------------------------------------- 1 | ![LOGO](images/omnirom_logo-big_layout_transparent-250px-150x150.png) 2 | # OmniROM Documents 3 | ## License templates 4 | Here are templates code code contributed to Omni. 5 | 6 | ***If your code contains code from other files, or is not a file you made, you should NOT replace the headers! See the "Adding to existing code" section*** 7 | 8 | ### XML 9 | ``` 10 | 25 | ``` 26 | 27 | ### Java 28 | ``` 29 | /* 30 | * Copyright (C) 2013-17 The OmniROM Project 31 | * 32 | * This program is free software: you can redistribute it and/or modify 33 | * it under the terms of the GNU General Public License as published by 34 | * the Free Software Foundation, either version 3 of the License, or 35 | * (at your option) any later version. 36 | * 37 | * This program is distributed in the hope that it will be useful, 38 | * but WITHOUT ANY WARRANTY; without even the implied warranty of 39 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 40 | * GNU General Public License for more details. 41 | * 42 | * You should have received a copy of the GNU General Public License 43 | * along with this program. If not, see . 44 | * 45 | */ 46 | ``` 47 | 48 | ### Python 49 | ```python 50 | # Copyright (C) 2013-17 The OmniROM Project 51 | # 52 | # This program is free software: you can redistribute it and/or modify 53 | # it under the terms of the GNU General Public License as published by 54 | # the Free Software Foundation, either version 3 of the License, or 55 | # (at your option) any later version. 56 | # 57 | # This program is distributed in the hope that it will be useful, 58 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 59 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 60 | # GNU General Public License for more details. 61 | # 62 | # You should have received a copy of the GNU General Public License 63 | # along with this program. If not, see . 64 | ``` 65 | 66 | ## Adding to existing code 67 | 68 | You should mention, as per article 5 of the Apache License, modifications have been made and are licensed under the GPLv3 license. 69 | 70 | Example: 71 | 72 | ``` 73 | /* 74 | * Copyright (C) 2009 The Android Open Source Project 75 | * 76 | * Licensed under the Apache License, Version 2.0 (the "License"); 77 | * you may not use this file except in compliance with the License. 78 | * You may obtain a copy of the License at 79 | * 80 | * http://www.apache.org/licenses/LICENSE-2.0 81 | * 82 | * Unless required by applicable law or agreed to in writing, software 83 | * distributed under the License is distributed on an "AS IS" BASIS, 84 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 85 | * See the License for the specific language governing permissions and 86 | * limitations under the License. 87 | * 88 | * Per article 5 of the Apache 2.0 License, some modifications to this code 89 | * were made by the OmniROM Project. 90 | * 91 | * Modifications Copyright (C) 2013-17 The OmniROM Project 92 | * 93 | * This program is free software; you can redistribute it and/or 94 | * modify it under the terms of the GNU General Public License 95 | * as published by the Free Software Foundation; either version 3 96 | * of the License, or (at your option) any later version. 97 | * 98 | * You should have received a copy of the GNU General Public License 99 | * along with this program; if not, write to the Free Software 100 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 101 | */ 102 | ``` 103 | -------------------------------------------------------------------------------- /Porting_Omni_To_Your_Device.md: -------------------------------------------------------------------------------- 1 | ![LOGO](images/omnirom_logo-big_layout_transparent-250px-150x150.png) 2 | # OmniROM Documents 3 | ## Porting Omni to your device 4 | ===== 5 | ### Introduction 6 | Omni is designed to use a basic AOSP device tree, with a few small modifications. This page will detail the necessary changes. 7 | 8 | ### Setup the base 9 | To begin, fork an already working device repo and delete their makefiles and stuff like `omni_[device].mk` and `omni.dependencies`. 10 | 11 | **Tip #1 - Never blindly edit anything that says full. If you do so, chances are your device won't boot.** 12 | 13 | ### Create the Omni make files 14 | 1. First you need to add a new make file for Omni. See the one below for an example: 15 | - https://github.com/omnirom/android_device_oneplus_oneplus3/blob/android-7.1/omni_oneplus3.mk 16 | 2. Add the makefile you created into `AndroidProducts.mk`. See the one below for an example: 17 | - https://github.com/omnirom/android_device_oneplus_oneplus3/blob/android-7.1/AndroidProducts.mk 18 | 3. Create a new file named `vendorsetup.sh`. See the one below for an example: 19 | - https://github.com/omnirom/android_device_oneplus_oneplus3/blob/android-7.1/vendorsetup.sh 20 | 4. Create a json file named `omni.dependencies` which will pull all of the necessary repos to build. See the one below for an example: 21 | - https://github.com/omnirom/android_device_oneplus_oneplus3/blob/android-7.1/omni.dependencies 22 | 23 | **Tip #2 - JSON files can be really annoying. Go to http://jsonlint.com/, paste in your json file and let it check for errors.** 24 | 25 | 5. You now need to setup your device tree for **Team Win Recovery Protocol, aka TWRP**. This usually consists of the following (visit this [link](http://forum.xda-developers.com/showthread.php?t=1943625) for more information): 26 | - adding TWRP specific build flags in `BoardConfig.mk` 27 | - creating `twrp.fstab` file 28 | - adding `twrp.fstab` to the **PRODUCT_COPY_FILES** make variable. 29 | 30 | That's it. If you did everything correctly, then you should have a working build. 31 | 32 | ### CAF Devices 33 | #### Android 7.0 34 | **Basic QCOM Support** 35 | 36 | To enable basic QCOM hardware support, the following must be added to your device's `BoardConfig.mk`: 37 | ``` 38 | BOARD_USES_QCOM_HARDWARE := true 39 | ``` 40 | Furthermore, QCOM_BSP support should be included in your device's `BoardConfig.mk` as follows: 41 | 42 | ``` 43 | TARGET_USES_QCOM_BSP := true 44 | ``` 45 | 46 | **Audio/Display/Media HAL** 47 | 48 | *hardware/qcom/[audio/display/media]* are separated on a per-platform basis. You must declare the HAL variant for your platform in your device's `BoardConfig.mk` via: 49 | 50 | ``` 51 | TARGET_QCOM_[AUDIO/DISPLAY/MEDIA]_VARIANT := caf-msm89** 52 | ``` 53 | 54 | **Enabling QCOM Audio/Video Enhancements** 55 | 56 | Include the following in your `BoardConfig.mk`: 57 | 58 | ``` 59 | TARGET_ENABLE_QC_AV_ENHANCEMENTS := true 60 | ``` 61 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![LOGO](images/omnirom_logo-big_layout_transparent-250px-150x150.png) 2 | 3 | # OmniROM Documents 4 | Documentation for Omni, replacing the wiki 5 | 6 | ## Contents 7 | - [Code of Conduct](https://github.com/omnirom/omni_community/blob/master/Code_of_Conduct.md) 8 | - [Contributor License Agreement](https://github.com/omnirom/omni_community/blob/master/Contributor_License_Agreement.md) 9 | - [Porting your device to Omni](https://github.com/omnirom/Docs/blob/master/Porting_Omni_To_Your_Device.md) 10 | -------------------------------------------------------------------------------- /images/Omnirom_logo-big_layout_transparent-300px.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/omnirom/Docs/b76e6cb0306ccb8950238717413eeb6ac3bf8f13/images/Omnirom_logo-big_layout_transparent-300px.png -------------------------------------------------------------------------------- /images/Omnirom_logo-big_layout_transparent.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/omnirom/Docs/b76e6cb0306ccb8950238717413eeb6ac3bf8f13/images/Omnirom_logo-big_layout_transparent.png -------------------------------------------------------------------------------- /images/Topic_gerrit_rules.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/omnirom/Docs/b76e6cb0306ccb8950238717413eeb6ac3bf8f13/images/Topic_gerrit_rules.png -------------------------------------------------------------------------------- /images/omnirom_logo-big_layout_transparent-250px-150x150.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/omnirom/Docs/b76e6cb0306ccb8950238717413eeb6ac3bf8f13/images/omnirom_logo-big_layout_transparent-250px-150x150.png --------------------------------------------------------------------------------