README: README optimize

Contributions to openEuler kernel project

=========================================

# How to Contribute

-------

Sign CLA

--------

-  [How to Contribute](#How to Contribute)

Before submitting any Contributions to openEuler, you have to sign CLA.

   \- [Sign the CLA](#Sign the CLA)

See:

     https://openeuler.org/zh/cla.html

     https://openeuler.org/en/cla.html

   \- [Steps of submitting patches](#Steps of submitting patches)

Steps of submitting patches

---------------------------

   \- [Use the unified patch format](#Use the unified patch format)

1. Compile and test your patches successfully.

2. Generate patches

   Your patches should be based on top of latest openEuler branch, and should

   use git-format-patch to generate patches, and if it's a patchset, it's

   better to use --cover-letter option to describe what the patchset does.

   \- [Define the patch format](#Define the patch format)

   Using scripts/checkpatch.pl to make sure there's no coding style issue.

   \- [Examples](#Examples)

   And make sure your patch follow unified openEuler patch format describe

   below.

   \- [Email client - Thunderbird settings](#Email client - Thunderbird settings)

3. Send patch to openEuler mailing list

   Use this command to send patches to openEuler mailing list:

-  [Linux kernel](#Linux kernel)

     git send-email *.patch -to="kernel@openeuler.org" --suppress-cc=all

###  Sign the CLA

   *NOTE*: that you must add --suppress-cc=all if you use git send-email,

   otherwise the email will be cced to the people in upstream community and mailing

   lists.

-------

   *See*: How to send patches using git-send-email

    https://git-scm.com/docs/git-send-email

Before making any contributions to openEuler, sign the CLA first.

4. Mark "v1, v2, v3 ..." in your patch subject if you have multiple versions

   to send out.

Address: [https://openeuler.org/en/cla.html](https://openeuler.org/en/cla.html)

   Use --subject-prefix="PATCH v2" option to add v2 tag for patchset.

     git format-patch --subject-prefix="PATCH v2" -1

### Steps of submitting patches

-------

**Step 1** Compile and test your patches.

**Step 2** Generate patches.

Your patches should be generated based on the latest openEuler branch using git-format-patch. If your patches are in a patchset, it is better to use the **--cover-letter** option to describe what the patchset does.

Use **scripts/checkpatch.pl** to ensure that no coding style issue exists.

In addition, ensure that your patches comply with the unified openEuler patch format described below.

**Step 3** Send your patches to the openEuler mailing list.

To do so, run the following command:

   `git send-email *.patch -to="kernel@openeuler.org" --suppress-cc=all`

*NOTE*: Add **--suppress-cc=all** if you use git-send-email; otherwise, the email will be copied to all people in the upstream community and mailing lists.

For details about how to send patches using git-send-email, see [https://git-scm.com/docs/git-send-email](https://git-scm.com/docs/git-send-email).

**Step 4** Mark "v1, v2, v3 ..." in your patch subject if you have multiple versions to send out.

Use the **--subject-prefix="PATCH v2"** option to add the v2 tag to the patchset.

   `git format-patch --subject-prefix="PATCH v2" -1`

Subject examples:

   Subject: [PATCH v2 01/27] fork: fix some -Wmissing-prototypes warnings

   Subject: [PATCH v3] ext2: improve scalability of bitmap searching

5. Upstream your kernel patch to kernel community is strongly recommended.

   openEuler will sync up with kernel master timely.

**Step 5** Upstream your kernel patches to the kernel community (recommended). openEuler will synchronize with the kernel master in a timely manner.

**Step 6** Sign your work - the Developer’s Certificate of Origin.

6. Sign your work - the Developer’s Certificate of Origin

   As the same of upstream kernel community, you also need to sign your patch.

 Similar to the upstream kernel community, you also need to sign your patch.

   See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html

 For details, see [https://www.kernel.org/doc/html/latest/process/submitting-patches.html](https://www.kernel.org/doc/html/latest/process/submitting-patches.html).

   The sign-off is a simple line at the end of the explanation for the patch,

   which certifies that you wrote it or otherwise have the right to pass it

   on as an open-source patch. The rules are pretty simple: if you can certify

   the below:

 The sign-off is a simple line at the end of the explanation of the patch, which certifies that you wrote it or otherwise have the  right to pass it on as an open source patch. The rules are pretty simple. You can certify as below:

  Developer’s Certificate of Origin 1.1

  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

  By making a contribution to this project, I certify that:

     (a) The contribution was created in whole or in part by me and I have

         the right to submit it under the open source license indicated in

         the file; or

   (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file;

     (b  The contribution is based upon previous work that, to the best of

         my knowledge, is covered under an appropriate open source license

         and I have the right under that license to submit that work with

         modifications, whether created in whole or in part by me, under

         the same open source license (unless I am permitted to submit under

         a different license), as indicated in the file; or

   (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file;

     (c) The contribution was provided directly to me by some other person

         who certified (a), (b) or (c) and I have not modified it.

   (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

     (d) I understand and agree that this project and the contribution are

         public and that a record of the contribution (including all personal

         information I submit with it, including my sign-off) is maintained

         indefinitely and may be redistributed consistent with this project

         or the open source license(s) involved.

   (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

   then you just add a line saying:

Then you add a line saying:

Signed-off-by: Random J Developer <random@developer.example.org>

   using your real name (sorry, no pseudonyms or anonymous contributions.)

Use your real name (sorry, no pseudonyms or anonymous contributions).

Use unified patch format

------------------------

### Use the unified patch format

-------

Reasons:

1. long term maintainability

1. Long term maintainability

  openEuler will merge massive patches. If all patches are merged by casual

   changelog format without a unified format, the git log will be messy, and

   then it's hard to figure out the original patch.

2. kernel upgrade

   We definitely will upgrade our openEuler kernel in someday, using strict

   patch management will alleviate the pain to migrate patches during big upgrade.

  changelog formats without a unified format, the git logs will be messy, and

  then it is hard to figure out the original patches.

2. Kernel upgrade

  We definitely will upgrade our openEuler kernel in someday, so strict patch management

  will alleviate the pain to migrate patches during big upgrades.

3. Easy for script parsing

3. easy for script parsing

  Keyword highlighting is necessary for script parsing.

Patch format definition

-----------------------

### Define the patch format

-------

[M] stands for "mandatory".

[O] stands for "option".

[M] stands for "mandatory"

[O] stands for "option"

$category can be: bug preparation, bugfix, perf, feature, doc, other...

If category is feature, then we also need to add feature name like below:

If category is feature, we need to add a feature name as below:

```cpp

category: feature

feature: YYY (the feature name)

```

If the patch is related to CVE or bugzilla, we need to add the corresponding tag as below (In general, it should include at least one of the following):

If the patch is related to CVE or bugzilla, then we need add the corresponding

tag like below (In general, it should include at least one of the following):

```cpp

CVE: $cve-id

bugzilla: $bug-id

```

Additional changelog should include at least one of the following:

Additional changelog should include at least one of the flollwing:

	1) Why we should apply this patch

	2) What real problem in product does this patch resolved

	3) How could we reproduce this bug or how to test

	4) Other useful information for help to understand this patch or problem

1.  Why we should apply this patch

The detail information is very useful for porting patch to another kenrel branch.

2. What real problems in the product does this patch resolved

3.  How could we reproduce this bug or how to test

4.  Other useful information for help to understand this patch or problem

The detailed information is very useful for migrating a patch to another kernel branch.

Example for mainline patch:

```cpp

mainline inclusion            [M]

from $mainline-version   [M]

commit $id                        [M]

--------------------------------

original changelog

Signed-off-by: $yourname <$yourname@huawei.com>  [M]

($mainline-version could be mainline-3.5, mainline-3.6, etc...)

```

Examples

--------

### Examples

-------

```cpp

mainline inclusion

from mainline-4.10

commit 0becc0ae5b42828785b589f686725ff5bc3b9b25

category: bugfix

bugzilla: 3004

CVE: NA

The patch fixes a BUG_ON in the product: injecting single bit ECC error

to memory before system boot use hardware inject tools, which cause a

large amount of CMCI during system booting .

CVE: N/A

The patch fixes a BUG_ON in the product: Injecting a single bit ECC error to the memory before system boot using hardware inject tools will cause a large amount of CMCI during system booting .

[   1.146580] mce: [Hardware Error]: Machine check events logged

[   1.152908] ------------[ cut here ]------------

[   1.157751] kernel BUG at kernel/timer.c:951!

[   1.162321] invalid opcode: 0000 [#1] SMP

...

-------------------------------------------------

<original S-O-B>

Signed-off-by: Zhang San <zhangsan@huawei.com>

Tested-by: Li Si <lisi@huawei.com>

```

Email Client - Thunderbird Settings

-----------------------------------

### Email client - Thunderbird settings

-------

If you are newly developer in the kernel community, it is highly recommended

to use thunderbird mail client.

If you are a new developer in the kernel community, it is highly recommended that you use the Thunderbird mail client.

1.  Thunderbird Installation

   Get English version Thunderbird from http://www.mozilla.org/ and install

   it on your system。

   Download url: https://www.thunderbird.net/en-US/thunderbird/all/

  Obtain the English version of Thunderbird from [http://www.mozilla.org/]( http://www.mozilla.org/) and install it on your system.

  Download URL: https://www.thunderbird.net/en-US/thunderbird/all/

2.  Settings

   2.1 Use plain text format instead of HTML format

       Options -> Account Settings -> Composition & Addressing, do *NOT* select

       "Compose message in HTML format".

   2.2 Editor Settings

       Tools->Options->Advanced->Config editor.

       - To bring up the thunderbird's registry editor, and set:

         "mailnews.send_plaintext_flowed" to "false".

       - Disable HTML Format: Set "mail.identity.id1.compose_html" to "false".

       - Enable UTF8: Set "prefs.converted-to-utf8" to "true".

       - View message in UTF-8: Set "mailnews.view_default_charset" to "UTF-8".

       - Set mailnews.wraplength to 9999 for avoiding auto-wrap

  2.1 Use the plain text format instead of the HTML format.

    Choose **Options > Account Settings > Composition & Addressing**, and do **NOT** select Compose message in HTML format.

  2.2 Editor settings

    **Tools > Options> Advanced > Config editor**

    \- To bring up the Thunderbird's registry editor, set **mailnews.send_plaintext_flowed** to **false**.

    \- Disable HTML Format: Set **mail.identity.id1.compose_html** to **false**.

    \- Enable UTF-8: Set **prefs.converted-to-utf8** to **true**.

    \- View messages in UTF-8: Set **mailnews.view_default_charset** to **UTF-8**.

    \- Set **mailnews.wraplength** to **9999** to avoid auto-wrap.

Linux kernel

============