blog.felipebalbi.com

Some references and other readings:

1. Documentation/CodingStyle;
2. Documentation/SubmittingPatches;
3. Documentation/SubmitChecklist;
4. git manual;
5. Linux Kernel Development 2nd Edition.

Hi again, everybody...

Let's discuss a bit about the common mistakes when preparing patches to send to LKML.

1. White spaces:
   Check and re-check if your patches have any extra white-spaces. Linux's subsystem maintainers DO NOT like trailing white-spaces.
   You can add this to you .vimrc in order to "detect" white-spaces. They'll be marked in red:highlight RedundantWhitespace ctermbg=red guibg=red
   match RedundantWhitespace /\s\+$\| \+\ze\t/
2. Bad indentation:
   Always follow the correct indentation defined in Documentation/CodingStyle. Never apply your own coding style. If you're unsure about how to indent you code, before committing, run the Lindent script in scripts/Lindent
3. CaMeLcAsE definitions:
   Don't use CaMeLcAsE, it will never get accepted. Separate words with _.
4. Ugly type-casts:
   Type casts are ugly in kernel, whenever you can find a way to do it better. For instance, use container_of() to avoid type-casts.
5. Missing Files:
   Before committing your changes check and re-check if you've added all the files to the commit-ish. If you leave a file out of the patch it won't get accepted since it won't work fine.
6. Including files that don't belong that patch:
   When producing patches you need to be aware about what are you really doing. Are you bug fixing or implementing better logic?
   When doing both, put them in separate patches to avoid confusing the community about your changes.
7. Huge Patch:
   If your patch is bigger than 40k, maybe is time to break it into a patch series. Keep that in mind.
8. Sending more than 15 patches at once:
   Try not to send more than 15 patches at once, you send patches whenever you want so when you get one bug fixed, you can release that patch right away.
9. HTML'd email:
   ONLY use plain text email. Never use html formated mails. Remeber: we use mutt.
10. Mails with MIME, links, compression and/or attachments:
    Patches should be inline, never attached. If you attach a patch, it become difficult to comment your code. Also, don't use MIME, don't use links (at least it's not usual) and never use compression.
11. #ifdefs are UGLY:
    There are lots of ways to avoid using #ifdefs, you should know about it. Read Documentation/SubmittingPatches to check the most common ways to achieve that.
12. Use static inline instead of MACROS:
    When you need to use some function in certain cases is better to use static inline instead of MACROS. Let's check an example:#ifdef CONFIG_BLABLA
    extern int foo(int bar);
    #else
    static inline int foo(int bar)
    {
    return 0;
    }
    #endif

    This is right way!

    #ifdef CONFIG_BLABLA
    extern int foo(int bar);
    #else
    #define foo(b) NULL
    #endif

Hello all,

Now we need to prepare a patch before sending it to the correct mailing list. We can do this by issuing:

$ git-format-patch -o patches_to_send

the start commit id must be one commit before yours, this is an open interval in the beginning and closed at the end (]a,b]).

After formating the patches, is nice to check if they're correct, if you're not missing anything, like white-spaces, commented code, unused variables, etc.

To test email config before sending the patches we just:

$ git-send-email --to mailing_list_address@domain.com --from "My Name " --dry-run patches_to_send

And to really send we just remove the --dry-run flag:

$ git-send-email --to mailing_list_address@domain.com --from "My Name " patches_to_send

Now that we know how to use git, we can start modifying the sources. In order to preserve the master branch (the one used when you update your git tree) we're gonna create a new one. Let's call it test. To do this, we just issue:

$ git-checkout -b test

A new branch called test will be created and you'll be switched to this branch.

Now we can edit any file. Do whatever addition, deletion, whatever you want to do with your tree. It's your branch anyway. After you finish, we can check what've we done with our tree. Issue:

$ git-status

To see which files we've modified/added/removed and also issue:

$ git-diff

To get a diff of your changes.

Now, that we've checked everything (it's compiling, it's what we want to do) we have to add files to the commit-ish:

$ git-add " file1 file2 ... fileN

And after that we run:

$ git-commit --author "My Name " -s

This will start commiting the changes to the current branch. It will open your default text editor for you to edit the commit message. Always use this format:

Small description of what are you doing

Big/detailed description of your changes, what are you implementing,
are you correcting a bug? which bug? how did you test it?
On which architectures did you test it?

Signed-off-by: My Name myemail@mydomain.com

Now we're entering into the subject. First we're gonna define git, who created it and which projects are already using git. So here we go:

Git is a SCM (Source Code Management) created by Linus Torvalds to become the
Bitkeeper's substitute. It's implemented in a distributed way, which means we don't need to stay connected to internet in order to work. We can produce patches whenever we want, wherever we are.

Git is being used in big projects such as:

• Linux Kernel (almost all trees);
• Xorg (every single module);
• GEDA (recently migrated);
• Others.

Git is really a big tool, really better then CVS or SVN, though it has a lot of commands, a lot of documentation and it'll take a while to understand how it works.

I'm listing the main commands every developer should know about git wiling this will help every single new developer to work better with git after 1 week playing around with it. So here we go, be careful :-p

• git-clone – Clone a git tree;
• git-checkout – Switch branches;
• git-log – Show the history;
• git-show-branch – Show where you are ([branch] Commit Msg);
• git-branch – List and create branches;
• git-diff e git-status – Show the actual state of your tree;
• git-commit – Apply your modifications into the current branch;
• git-reset – Undo changes;
• git-pull – Update or merge a tree;
• git-merge – Merge local branches
• git-rebase – Maintain branches;
• git-tag – Create, list, remove a tag;
• git-add – Add files to the current commit-ish

In later posting we'll study every single command in this list.

We can define a patch the following way:

• diff -u
• Improvements/corrections to pre-existing code;
• Implementation of new feature;
• File Deletion / Creation / Renaming;
• Code modification;

A patch can have all of these definitions and even more, but let's produce a nice and easy-remembering phrase for those topics over there:
"A patch is any kind of modification in a source-code tree"

Hello all,

This will be a series of posts here.
this is our agenda:

- What is a patch
- git overview
- Creating patches
- Testing your patches
- Sending patches (the right/better way)