Readme.md

   1 # EDK II Project
   2
   3 A modern, feature-rich, cross-platform firmware development environment
   4 for the UEFI and PI specifications from www.uefi.org.
   5
   6 The majority of the content in the EDK II open source project uses a
   7 [BSD-2-Clause Plus Patent License](License.txt).  The EDK II open source project
   8 contains the following components that are covered by additional licenses:
   9 * [BaseTools/Source/C/BrotliCompress](BaseTools/Source/C/BrotliCompress/LICENSE)
  10 * [MdeModulePkg/Library/BrotliCustomDecompressLib](MdeModulePkg/Library/BrotliCustomDecompressLib/LICENSE)
  11 * [BaseTools/Source/C/LzmaCompress](BaseTools/Source/C/LzmaCompress/LZMA-SDK-README.txt)
  12 * [MdeModulePkg/Library/LzmaCustomDecompressLib](MdeModulePkg/Library/LzmaCustomDecompressLib/LZMA-SDK-README.txt)
  13 * [IntelFrameworkModulePkg/Library/LzmaCustomDecompressLib/Sdk](IntelFrameworkModulePkg/Library/LzmaCustomDecompressLib/LZMA-SDK-README.txt)
  14 * [BaseTools/Source/C/VfrCompile/Pccts](BaseTools/Source/C/VfrCompile/Pccts/RIGHTS)
  15 * [MdeModulePkg/Universal/RegularExpressionDxe/Oniguruma](MdeModulePkg/Universal/RegularExpressionDxe/Oniguruma/README)
  16 * [OvmfPkg](OvmfPkg/License.txt)
  17 * [CryptoPkg/Library/OpensslLib/openssl](https://github.com/openssl/openssl/blob/50eaac9f3337667259de725451f201e784599687/LICENSE)
  18 * [ArmPkg/Library/ArmSoftFloatLib/berkeley-softfloat-3](https://github.com/ucb-bar/berkeley-softfloat-3/blob/b64af41c3276f97f0e181920400ee056b9c88037/COPYING.txt)
  19
  20 The EDK II Project is composed of packages.  The maintainers for each package
  21 are listed in [Maintainers.txt](Maintainers.txt).
  22
  23 # Resources
  24 * [TianoCore](http://www.tianocore.org)
  25 * [EDK II](https://github.com/tianocore/tianocore.github.io/wiki/EDK-II)
  26 * [Getting Started with EDK II](https://github.com/tianocore/tianocore.github.io/wiki/Getting-Started-with-EDK-II)
  27 * [Mailing Lists](https://github.com/tianocore/tianocore.github.io/wiki/Mailing-Lists)
  28 * [TianoCore Bugzilla](https://bugzilla.tianocore.org)
  29 * [How To Contribute](https://github.com/tianocore/tianocore.github.io/wiki/How-To-Contribute)
  30 * [Release Planning](https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Release-Planning)
  31
  32 # Code Contributions
  33 To make a contribution to a TianoCore project, follow these steps.
  34 1. Create a change description in the format specified below to
  35    use in the source control commit log.
  36 2. Your commit message must include your `Signed-off-by` signature
  37 3. Submit your code to the TianoCore project using the process
  38    that the project documents on its web page.  If the process is
  39    not documented, then submit the code on development email list
  40    for the project.
  41 4. It is preferred that contributions are submitted using the same
  42    copyright license as the base project. When that is not possible,
  43    then contributions using the following licenses can be accepted:
  44    * BSD (2-clause): http://opensource.org/licenses/BSD-2-Clause
  45    * BSD (3-clause): http://opensource.org/licenses/BSD-3-Clause
  46    * MIT: http://opensource.org/licenses/MIT
  47    * Python-2.0: http://opensource.org/licenses/Python-2.0
  48    * Zlib: http://opensource.org/licenses/Zlib
  49
  50    For documentation:
  51    * FreeBSD Documentation License
  52      https://www.freebsd.org/copyright/freebsd-doc-license.html
  53
  54    Contributions of code put into the public domain can also be
  55    accepted.
  56
  57    Contributions using other licenses might be accepted, but further
  58    review will be required.
  59
  60 # Developer Certificate of Origin
  61
  62 Your change description should use the standard format for a
  63 commit message, and must include your `Signed-off-by` signature.
  64
  65 In order to keep track of who did what, all patches contributed must
  66 include a statement that to the best of the contributor's knowledge
  67 they have the right to contribute it under the specified license.
  68
  69 The test for this is as specified in the [Developer's Certificate of
  70 Origin (DCO) 1.1](https://developercertificate.org/). The contributor
  71 certifies compliance by adding a line saying
  72
  73   Signed-off-by: Developer Name <developer@example.org>
  74
  75 where `Developer Name` is the contributor's real name, and the email
  76 address is one the developer is reachable through at the time of
  77 contributing.
  78
  79 ```
  80 Developer's Certificate of Origin 1.1
  81
  82 By making a contribution to this project, I certify that:
  83
  84 (a) The contribution was created in whole or in part by me and I
  85     have the right to submit it under the open source license
  86     indicated in the file; or
  87
  88 (b) The contribution is based upon previous work that, to the best
  89     of my knowledge, is covered under an appropriate open source
  90     license and I have the right under that license to submit that
  91     work with modifications, whether created in whole or in part
  92     by me, under the same open source license (unless I am
  93     permitted to submit under a different license), as indicated
  94     in the file; or
  95
  96 (c) The contribution was provided directly to me by some other
  97     person who certified (a), (b) or (c) and I have not modified
  98     it.
  99
 100 (d) I understand and agree that this project and the contribution
 101     are public and that a record of the contribution (including all
 102     personal information I submit with it, including my sign-off) is
 103     maintained indefinitely and may be redistributed consistent with
 104     this project or the open source license(s) involved.
 105 ```
 106
 107 # Sample Change Description / Commit Message
 108
 109 ```
 110 From: Contributor Name <contributor@example.com>
 111 Subject: [Repository/Branch PATCH] Pkg-Module: Brief-single-line-summary
 112
 113 Full-commit-message
 114
 115 Signed-off-by: Contributor Name <contributor@example.com>
 116 ```
 117
 118 ## Notes for sample patch email
 119
 120 * The first line of commit message is taken from the email's subject
 121   line following `[Repository/Branch PATCH]`. The remaining portion of the
 122   commit message is the email's content.
 123 * `git format-patch` is one way to create this format
 124
 125 ## Definitions for sample patch email
 126
 127 * `Repository` is the identifier of the repository the patch applies.
 128   This identifier should only be provided for repositories other than
 129   `edk2`. For example `edk2-BuildSpecification` or `staging`.
 130 * `Branch` is the identifier of the branch the patch applies. This
 131   identifier should only be provided for branches other than `edk2/master`.
 132   For example `edk2/UDK2015`, `edk2-BuildSpecification/release/1.27`, or
 133   `staging/edk2-test`.
 134 * `Module` is a short identifier for the affected code or documentation. For
 135   example `MdePkg`, `MdeModulePkg/UsbBusDxe`, `Introduction`, or
 136   `EDK II INF File Format`.
 137 * `Brief-single-line-summary` is a short summary of the change.
 138 * The entire first line should be less than ~70 characters.
 139 * `Full-commit-message` a verbose multiple line comment describing
 140   the change.  Each line should be less than ~70 characters.
 141 * `Signed-off-by` is the contributor's signature identifying them
 142   by their real/legal name and their email address.
 143
 144 # Submodules
 145
 146 Submodule in EDK II is allowed but submodule chain should be avoided
 147 as possible as we can. Currently EDK II contains the following submodules
 148
 149 - CryptoPkg/Library/OpensslLib/openssl
 150 - ArmPkg/Library/ArmSoftFloatLib/berkeley-softfloat-3
 151
 152 ArmSoftFloatLib is actually required by OpensslLib. It's inevitable
 153 in openssl-1.1.1 (since stable201905) for floating point parameter
 154 conversion, but should be dropped once there's no such need in future
 155 release of openssl.
 156
 157 To get a full, buildable EDK II repository, use following steps of git
 158 command
 159
 160 ```
 161 $ git clone https://github.com/tianocore/edk2.git
 162 $ cd edk2
 163 $ git submodule update --init
 164 $ cd ..
 165 ```
 166
 167 If there's update for submodules, use following git commands to get the
 168 latest submodules code.
 169
 170 ```
 171 $ cd edk2
 172 $ git pull
 173 $ git submodule update
 174 ```
 175
 176 Note: When cloning submodule repos, '--recursive' option is not
 177 recommended. EDK II itself will not use any code/feature from
 178 submodules in above submodules. So using '--recursive' adds a
 179 dependency on being able to reach servers we do not actually want
 180 any code from, as well as needlessly downloading code we will not
 181 use.