Added description of essential project files. Reformated and checked old text.
authorOleksandr Gavenko <gavenkoa@gmail.com>
Sat, 04 Dec 2010 22:35:01 +0200
changeset 736 9b962c4c86e3
parent 735 5c437e2d5fe1
child 737 e0b618d34942
Added description of essential project files. Reformated and checked old text.
devel-ideal-proj.rst
--- a/devel-ideal-proj.rst	Sat Dec 04 17:10:45 2010 +0200
+++ b/devel-ideal-proj.rst	Sat Dec 04 22:35:01 2010 +0200
@@ -1,45 +1,110 @@
--*- mode: outline; coding: utf-8 -*-
+-*- mode: outline; coding: utf-8; fill-column: 80 -*-
 
-                      Ideal software development model.
+* Ideal software development model.
 
+This file mainly discuss about open source software project.
 
 * Open source.
 
-Open source development have much freedom select any development model.
-
+Open source software project have freedom how develop project and which
+development toolchains use.
 
 * Close source.
 
-Close source sortware development restrict in using models, technic or
-software resources; restrict their public appear because of its proprietary
-nature.
+Close source projects have proprietary nature because of:
+
+ * interest to make money (another parties can not easily reproduce project or
+   steal realisation ideas/code, allowing another party get same product and get
+   company money)
+ * low code quality (to stop stain company good name or to stop malicious
+   attacks based on code analysis)
+ * security consideration (to hide protocols and data format to make harder
+   malicious attack)
+ * business model (closed data formats allow vendor lock)
+
+Disadvantage of closed source project (in many case):
+
+ * you can not directly contact with developers (only through support)
+ * low support quality
+ * paid support (and you have no enough money)
+ * can not access to product bug tracing system (you only can submit bug via
+   crash report application or technical support, publicly appear internal bug
+   tracing can damage product reputation
 
-In many case you can not directly contact with developers (only through
-support). You can not access to product bug tracing system (you only can
-submit bug via crash report application or technical support); publicly appear
-internal bug tracing can damage product reputation. Internal
-architecture/protocol description can drop leading product position (allowing
-another party get same product and get company money).
+* Component of software project.
+
+ * Src (sources).
+ * Doc (documentation).
+ * VCS (version control system).
+ * BTS (bug tracking).
+ * News (project news/history/changelog).
+
+* Project sources.
 
-* Component.
+** README file.
+
+Assumed that users first read this file before start using project.
+
+ * Project name.
+ * Project goal.
+ * Point to license statements.
+ * Point to build instructions.
+ * Point to documentations.
+
+** INSTALL file.
 
- * Docs.
- * VCS.
- * Bug track.
- * News.
+ * List of supported platform.
+ * Build dependencies/prerequisites.
+ * Build instructions.
+
+** COPYING/LICENSE file.
+
+COPYING usually used for GNU GPL like license. Another license put in LICENSE
+file.
+
+If some component comes with different license put it into file with name like:
+
+  LICENSE.libmy LICENSE.regex LICENSE.doc
+
+** AUTHORS file.
+
+Usually regular contributors.
+
+ * List of project members.
+
+** THANKS/CREDITS file.
+
+Usually casual/non-regular contributors.
 
-** Docs.
+ * List of contributors.
+
+** NEWS/CHANGES file.
 
-Documentation must provide:
+Here goes news and descriptions of user visible changes:
+
+ * Important project news.
+ * New features.
+ * Obsolescense/deprecation of UIs/APIs/protocols/formats.
+ * Incompatibilities with previous version.
 
-** Home page.
+** HISORY file.
+
+ * Project history in long perspective.
+
+** FAQ file.
 
-Home page must provide:
+ * List of frequency asked questions with answers.
+
+* Docs.
+
+* Project home page.
+
+Project home page must provide:
 
  * project name
  * short info about project goal
- * project licence (COPYING)
- * currect project status
+ * project license
+ * current project status
  * links to binary release
  * links to source release, how to get latest source from VCS
  * links to online/printed docs
@@ -58,7 +123,7 @@
  * list of contributor with contact info (MAINTAINERS, AUTHORS)
  * who use project
 
-** VCS.
+* VCS.
 
 TAGS: VCS, version control system, SCM, source code management, DVCS,
       distributed version control system.
@@ -69,13 +134,3 @@
  * git
  * bazaar
 
-*** CVS
-
-*** SVN
-
-*** Mercurial (hg)
-
-*** git
-
-*** bazaar
-