Add documentation on how to write good descriptions for changes.

Review Request #6858 — Created Jan. 31, 2015 and submitted

Information

Review Board
master
cc261fd...

Reviewers

A common problem encountered by new contributors to the project is that
the commit messages or review request descriptions aren't always
sufficient to describe the change without requiring additional
information from a bug report or diff. Sometimes they focus on
referencing bug numbers or filenames, and sometimes they don't go into
what the core problem was that the change addressed. This makes it
harder to write release notes or to scan for review requests for a given
topic.

This adds a page to the codebase documentation explaining guidelines and
tips for writing good review request and commit descriptions. It's
broken down into sections for summaries, descriptions, testing, and
general writing tips.

Built the docs and viewed them. Formatting looked correct.

Ran spell checker. Didn't see any spelling errors.

Description From Last Updated

Can we add a new paragraph in here? Writing good change descriptions is first and foremost a question of good …

daviddavid

Writign

daviddavid

wrongs -> wrong

daviddavid

How about "Make sure that your spelling and grammar is correct"? I don't want minor errors either :)

daviddavid

grammer?

daviddavid
reviewbot
  1. Tool: PEP8 Style Checker
    Ignored Files:
        docs/codebase/writing-good-descriptions.rst
        docs/codebase/git/clean-commits.rst
        docs/codebase/contributing-patches.rst
        docs/codebase/index.rst
    
    
    
    Tool: Pyflakes
    Ignored Files:
        docs/codebase/writing-good-descriptions.rst
        docs/codebase/git/clean-commits.rst
        docs/codebase/contributing-patches.rst
        docs/codebase/index.rst
    
    
  2. 
      
david
  1. 
      
  2. docs/codebase/writing-good-descriptions.rst (Diff revision 1)
     
     
     
     
    Show all issues

    Can we add a new paragraph in here?

    Writing good change descriptions is first and foremost a question of good writing. Make sure that everything you write uses full sentences with proper spelling and capitalization.

  3. Show all issues

    wrongs -> wrong

  4. docs/codebase/writing-good-descriptions.rst (Diff revision 1)
     
     
     
    Show all issues

    How about "Make sure that your spelling and grammar is correct"? I don't want minor errors either :)

  5. 
      
chipx86
reviewbot
  1. Tool: PEP8 Style Checker
    Ignored Files:
        docs/codebase/writing-good-descriptions.rst
        docs/codebase/git/clean-commits.rst
        docs/codebase/contributing-patches.rst
        docs/codebase/index.rst
    
    
    
    Tool: Pyflakes
    Ignored Files:
        docs/codebase/writing-good-descriptions.rst
        docs/codebase/git/clean-commits.rst
        docs/codebase/contributing-patches.rst
        docs/codebase/index.rst
    
    
  2. 
      
chipx86
david
  1. 
      
  2. docs/codebase/writing-good-descriptions.rst (Diff revisions 1 - 2)
     
     
    Show all issues

    Writign

  3. docs/codebase/writing-good-descriptions.rst (Diff revisions 1 - 2)
     
     
    Show all issues

    grammer?

  4. 
      
reviewbot
  1. Tool: Pyflakes
    Ignored Files:
        docs/codebase/writing-good-descriptions.rst
        docs/codebase/git/clean-commits.rst
        docs/codebase/contributing-patches.rst
        docs/codebase/index.rst
    
    
    
    Tool: PEP8 Style Checker
    Ignored Files:
        docs/codebase/writing-good-descriptions.rst
        docs/codebase/git/clean-commits.rst
        docs/codebase/contributing-patches.rst
        docs/codebase/index.rst
    
    
  2. 
      
david
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to master (99002b6)