OpenCores
URL https://opencores.org/ocsvn/dirac/dirac/trunk

Subversion Repositories dirac

[/] [dirac/] [trunk/] [README.developers] - Diff between revs 5 and 12

Go to most recent revision | Show entire file | Details | Blame | View Log

Rev 5 Rev 12
?rev1line?
?rev2line?
 
 
 
 
 
Dirac development practices
 
======================
 
 
 
Contents
 
--------
 
 
 
1. Licenses and submitting work
 
 
 
2. Sourceforge Developers forum
 
 
 
3. Mailing lists
 
 
 
4. Using the CVS repository
 
 
 
5. CVS log messages
 
 
 
6. Design practices
 
 
 
7. Line-endings
 
 
 
8. Binary files in CVS
 
 
 
 
 
 
 
1. Licenses and submitting work
 
-------------------------------
 
 
 
Developers submitting work to the Dirac project should print out,
 
complete, and sign the Developer's Certificate of Origin contained
 
in the DCO.developers file. It should be posted to:
 
 
 
Dr Tim Borer
 
BBC Research and Development
 
Kingswood Warren
 
Tadworth
 
Surrey KT20 6NP
 
United Kingdom
 
 
 
For simplicity developers must submit code using the same
 
license that we distribute under, which is the Mozilla Triple
 
license (http://www.mozilla.org/MPL/). Using any other license
 
causes complexity and FUD.
 
 
 
Contributions should be in the form of a patch, which may be for a
 
whole directory. For changes to an existing file all that is needed
 
is to add the author's name to the list of contributors, since the
 
license will remain the MPL. For new files, the header in each file
 
should be completed from Exhibit A, the Mozilla Triple License (from the
 
COPYING file). It should NOT be copied from files already obtained
 
in the Dirac project, since some details may differ.
 
 
 
To create a context diff patch run the command
 
 
 
diff -ruN compress-orig compress-mods > patch.txt
 
 
 
   where compress-orig is the directory with the original code and
 
   compress-mods is the directory with the modified files.
 
 
 
The patch.txt file should then be submitted to the Sourceforge Patch
 
tracker.
 
 
 
2. Sourceforge Developers forum
 
-------------------------------
 
The Developers forum is where Dirac core developers plan and coordinate
 
changes to Dirac.  All API changes, new features and implementation
 
difficulties are announced and discussed here.
 
 
 
Examples of changes which should be announced in the Developers forum:
 
 
 
  - Pic API change: return bool instead of void for ReadNextFrame
 
  - Pic API change: most methods can now throw ErrorState objects
 
 
 
Changes which are small in scope and unlikely to affect developers
 
should not be announced on the forum.  Changes which touch
 
many files can fall into this category - for example
 
 
 
  - Fixed inconsistent CRLF line-endings to be LF.
 
  - Fixed "use of uninitialised variable" cases found by gcc.
 
  - Fixed memory leak in all instantiations of Pic (found by valgrind).
 
  - Add feature test for stdint.h to be portable to Solaris.
 
 
 
Developers should 'monitor' the forums by going to the forum page and
 
clicking 'Monitor this forum'.  Any new message will then be emailed
 
to their username@users.sourceforge.net  email address.
 
  http://sourceforge.net/forum/forum.php?forum_id=353620
 
 
 
 
 
3. Mailing lists
 
----------------
 
Developers should subscribe to the dirac-announce and dirac-commits
 
mailing lists.  dirac-announce is used to announce new releases and
 
dirac-commits is sent mail automatically for every commit.
 
 
 
 
 
4. Using the CVS repository
 
---------------------------
 
 
 
The latest (but non-stable) version of the code can be downloaded direct
 
from the Sourceforge repository using anonymous CVS. Instructions for
 
doing so can be found at the Dirac CVS page:
 
 
 
http://sourceforge.net/cvs/
 
 
 
The Dirac codec module is called 'diracvhdl'.
 
 
 
5. CVS log messages
 
-------------------
 
Always indicate why the change is necessary in addition to a succinct summary
 
of what as changed.  As the number of developers increases it becomes
 
increasingly difficult for developers to understand the changes going on in
 
areas they are not familiar with.  If the changes relate to an API change
 
developers may not realise this if it is not mentioned in the log message
 
as the reason for the change.
 
 
 
E.g.
 
  Bad
 
  ---
 
  - Added gamma parameter
 
  - Replace stricmp with strcasecmp
 
 
 
  Good
 
  ----
 
  - Added gamma parameter to record more accurate data on source material
 
  - Enhanced portability: stricmp replaced by strcasecmp (the POSIX standard)
 
 
 
 
 
6. Design practices
 
---------------------
 
 
 
I. Coding Style
 
 
 
   The following guidelines must be adhered to while developing code.
 
 
 
-- CVS related tags
 
 
 
 - Include the following RCS tags in all new files (.vhd). Include them
 
   on the first line of the licence block
 
 
 
   Id
 
   Name
 
 
 
   E.g.
 
   -- /* ***** BEGIN LICENSE BLOCK *****
 
   -- *
 
   -- * $Id: README.developers,v 1.2 2005-05-27 16:00:27 petebleackley Exp $ $Name: not supported by cvs2svn $
 
   -- *
 
   -- *  rest of licence text
 
   -- * ***** END LICENSE BLOCK ***** */
 
 
 
 
 
 - Remove the following tags from all files. Do not include them in new files
 
   Author
 
   Revision
 
   Log
 
 
 
--  General Source code formatting
 
 
 
 All signals should be std_logic or std_logic_vector.
 
 Widths and slices of vectors should be specified with downto.
 
 VHDL '97 style is preferred for end statements (e.g. end architecture RTL;)
 
 VHDL keywords should be in lower case, entity, architecture and signal names, and other user-defined names in upper case
 
 When instantiating a component, use both positional association and named association, ie the "belt and braces" approach.
 
 
 
 
 
 
 
III. Code Review
 
 
 
   All code will be peer-reviewed before being checked in to SourceForge
 
   CVS. Developers should use the guidelines specified in the Coding Style
 
   sub-section while reviewing code.
 
 
 
7. Line-endings
 
---------------
 
All source code and documentation will have LF line-endings, include makefiles
 
and scripts.
 
 
 
 
 
8. Binary files in CVS
 
----------------------
 
CVS will modify files during checkin and checkout unless they are tagged as
 
binary.  The modifications include translation of CR-LF <-> LF (depending on
 
the OS of the CVS client) and expansion of CVS keywords such as $Id and $Log.
 
 
 
Files which must not be modified in this way must be tagged as binary either
 
using the add command or admin command:
 
  cvs add -kb fig1.jpg
 
  cvs admin -kb fig1.jpg  (for files already in CVS)
 
 
 
MS VC++ project files, such as .vcproj and .sln, fall into this category since
 
they do not function if their line-endings are not CR-LF.
 
 
 
------------------------------------------------------------------------

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.