Architecture - Writing Architecture Documents - Revision history

Docadmin: Protected "Architecture - Writing Architecture Documents" ([edit=sysop] (indefinite) [move=sysop] (indefinite))

2010-01-20T23:52:15Z

Protected "Architecture - Writing Architecture Documents" ([edit=sysop] (indefinite) [move=sysop] (indefinite))

← Older revision	Revision as of 16:52, 20 January 2010
(No difference)

Docadmin: /* Process Outline */

2010-01-19T23:01:47Z

Process Outline

← Older revision		Revision as of 16:01, 19 January 2010
Line 70:		Line 70:
	#* your project manager will help broker this step for you		#* your project manager will help broker this step for you
	#* the key customers for each feature are identified in the Architectural Features Google spreadsheet		#* the key customers for each feature are identified in the Architectural Features Google spreadsheet
	#* discuss relevant feedback on the ''lustre-devel'' mailing list@ and revise the architecture as required		#* discuss relevant feedback on the ''lustre-devel'' mailing list and revise the architecture as required
	# Cross reference		# Cross reference
	#* Add bugzilla link to architecture pages (in a Reference section at the bottom)		#* Add bugzilla link to architecture pages (in a Reference section at the bottom)

Docadmin: /* Process Outline */

2010-01-19T23:01:24Z

Process Outline

Docadmin: /* Process Outline */

2010-01-19T23:00:09Z

Process Outline

← Older revision		Revision as of 16:00, 19 January 2010
Line 21:		Line 21:
	#* the Responsible Architect(s) column		#* the Responsible Architect(s) column
	#** identifies who needs to generate the architecture		#** identifies who needs to generate the architecture
	#** is populated initially based on the current engineering organization, but may change based on priorities and negotiation ~~with arch@~~		#** is populated initially based on the current engineering organization, but may change based on priorities and negotiation on the ''lustre-devel'' mailing list
	#** the first person is the list is "on the hook" to deliver; project managers will be coming after you to complete this work		#** the first person is the list is "on the hook" to deliver; project managers will be coming after you to complete this work
	#** the others architects are responsible for contributing to the design		#** the others architects are responsible for contributing to the design

Docadmin: /* General Guidelines */

2010-01-19T22:59:24Z

General Guidelines

← Older revision		Revision as of 15:59, 19 January 2010
Line 7:		Line 7:

	== General Guidelines ==		== General Guidelines ==
	* Discuss everything on the lustre-devel mailing ~~lis~~; avoid private discussions until the choices are accepted		* Discuss everything on the ''lustre-devel'' mailing list; avoid private discussions until the choices are accepted
	* Arch pages should be short and sweet; if printed, most components would fit 1-2 pages; major components maybe 5-10 (say for the LRE)		* Arch pages should be short and sweet; if printed, most components would fit 1-2 pages; major components maybe 5-10 (say for the LRE)
	* Take care with formatting, make them look nice -- people can read these all over		* Take care with formatting, make them look nice -- people can read these all over

Docadmin: /* General Guidelines */

2010-01-19T22:59:05Z

General Guidelines

← Older revision		Revision as of 15:59, 19 January 2010
Line 7:		Line 7:

	== General Guidelines ==		== General Guidelines ==
	* Discuss everything on ~~arch@~~; avoid private discussions until the choices are accepted		* Discuss everything on the lustre-devel mailing lis; avoid private discussions until the choices are accepted
	* Arch pages should be short and sweet; if printed, most components would fit 1-2 pages; major components maybe 5-10 (say for the LRE)		* Arch pages should be short and sweet; if printed, most components would fit 1-2 pages; major components maybe 5-10 (say for the LRE)
	* Take care with formatting, make them look nice -- people can read these all over		* Take care with formatting, make them look nice -- people can read these all over

Docadmin at 22:58, 19 January 2010

2010-01-19T22:58:22Z

← Older revision		Revision as of 15:58, 19 January 2010
Line 1:		Line 1:
	~~Lustre Architecture Process~~		This page provides some guidelines for preparing architecture documents.

	== Resources ==		== Resources ==

Docadmin: /* General Guidelines */

2010-01-19T22:57:17Z

General Guidelines

← Older revision		Revision as of 15:57, 19 January 2010
Line 9:		Line 9:
	* Discuss everything on arch@; avoid private discussions until the choices are accepted		* Discuss everything on arch@; avoid private discussions until the choices are accepted
	* Arch pages should be short and sweet; if printed, most components would fit 1-2 pages; major components maybe 5-10 (say for the LRE)		* Arch pages should be short and sweet; if printed, most components would fit 1-2 pages; major components maybe 5-10 (say for the LRE)
	* ~~Rake~~ care with formatting, make them look ~~nicely~~ -- people can read these all over		* Take care with formatting, make them look nice -- people can read these all over
	* Use consistent formatting:		* Use consistent formatting:
	** Summary QAS features - [[Architecture - Simple_Space_Balance_Migration\|Simple Space Balance Migration]]		** Summary QAS features - [[Architecture - Simple_Space_Balance_Migration\|Simple Space Balance Migration]]

Docadmin: /* Resources */

2010-01-19T22:56:55Z

Resources

← Older revision		Revision as of 15:56, 19 January 2010
Line 3:		Line 3:
	== Resources ==		== Resources ==
	* SEI books - Documenting Software Architectures, Software Architecture in Practice		* SEI books - Documenting Software Architectures, Software Architecture in Practice
	* ~~arch@~~ - the ~~Architecture team~~ mailing list ~~where all architectural discussion should be taking place~~		* [[Lustre Mailing Lists]] - in particular, the ''lustre-devel'' mailing list used by Lustre developers to discuss Lustre internals, code changes, and other topics of interest to developers.
	* Lustre ~~architecture wiki site - arch.lustre.org~~
	* Lustre ~~Architectural Features Google spreadsheet - http://spreadsheets.google.com/a/wiki.lustre~~.~~org/ccc?key=pMf3Udi56jKwFpCMJDq-Mbg&hl=en~~
	* Good example of a feature architecture - [[Architecture - Simple_Space_Balance_Migration\|Simple Space Balance Migration]]		* Good example of a feature architecture - [[Architecture - Simple_Space_Balance_Migration\|Simple Space Balance Migration]]
	* Task Planning Worksheet form - https://wiki.lustre.org/intra/index.php/Task_Planning_Work_Sheets

	== General Guidelines ==		== General Guidelines ==

Docadmin: /* Examples */

2010-01-19T22:53:49Z

Examples

← Older revision		Revision as of 15:53, 19 January 2010
Line 84:		Line 84:
	* [[Architecture - Simple_Space_Balance_Migration\|Simple Space Balance Migration]]		* [[Architecture - Simple_Space_Balance_Migration\|Simple Space Balance Migration]]
	* [[Architecture - Client_Cleanup\|Client Cleanup]] - for bigger projects sometimes one separates out a whole page of QAS (requirements)		* [[Architecture - Client_Cleanup\|Client Cleanup]] - for bigger projects sometimes one separates out a whole page of QAS (requirements)
	* http://arch.lustre.org/index.php?title=VS_LRE - a larger introduction for the LRE project; this has some elements we did not discuss here, and which are generally not necessary
	* http://arch.lustre.org/index.php?title=QAS_LRE - has many use cases and several detailed ones, done with customers

← Older revision		Revision as of 16:01, 19 January 2010
Line 41:		Line 41:
	## document this on your assigned architecture wiki page. If there are many, start a separate QAS page		## document this on your assigned architecture wiki page. If there are many, start a separate QAS page
	# Review use cases with Chief Architect and architecture team		# Review use cases with Chief Architect and architecture team
	#* send an email to ~~arch@~~, requesting an inspection for your high level use cases; specify your architecture wiki page for convenience		#* send an email to the ''lustre-devel'' mailing list, requesting an inspection for your high level use cases; specify your architecture wiki page for convenience
	#* this is an important quality gating step; be sure to get approval and make required updates before proceeding		#* this is an important quality gating step; be sure to get approval and make required updates before proceeding
	# Review use cases with key customers		# Review use cases with key customers
Line 47:		Line 47:
	#* the key customers for each feature are identified in the Architectural Features Google spreadsheet		#* the key customers for each feature are identified in the Architectural Features Google spreadsheet
	#* ask them to review and provide questions and feedback on the use cases; in particular, have we overlooked any key scenarios?		#* ask them to review and provide questions and feedback on the use cases; in particular, have we overlooked any key scenarios?
	#* discuss relevant feedback ~~with arch@~~ and revise use cases as required		#* discuss relevant feedback on the ''lustre-devel'' mailing list and revise use cases as required
	# Decompose the problem into a more detailed architectural definition		# Decompose the problem into a more detailed architectural definition
	#* almost all architecture starts by decomposing the problem		#* almost all architecture starts by decomposing the problem
	#* write down the subsystems and the functionality and interfaces offered by each		#* write down the subsystems and the functionality and interfaces offered by each
	#* often a list of definitions is useful, like "agent = a daemon receiving commands to move data", "coordinator == a daemon running on ... " etc.		#* often a list of definitions is useful, like "agent = a daemon receiving commands to move data", "coordinator == a daemon running on ... " etc.
	#* it is pretty important that the ~~deomposition~~ leaves no doubt about what happens where		#* it is pretty important that the decomposition leaves no doubt about what happens where
	# Write detailed behavioral architecture		# Write detailed behavioral architecture
	## Write detailed attribute scenarios		## Write detailed attribute scenarios
Line 64:		Line 64:
	##* use cases can contain exact command invocations: type mkfs.lustre --mds ...... (all arguments ) to achieve ......		##* use cases can contain exact command invocations: type mkfs.lustre --mds ...... (all arguments ) to achieve ......
	# Review architecture with architecture team		# Review architecture with architecture team
	#* send an email to ~~arch@~~, requesting an inspection for your draft architecture document; specify your architecture wiki page for convenience		#* send an email to the ''lustre-devel'' mailing list, requesting an inspection for your draft architecture document; specify your architecture wiki page for convenience
	#* We follow the benevolent dictatorship model, we are done when Braam says we are done.		#* We follow the benevolent dictatorship model, we are done when Braam says we are done.
	#* Typically several weeks are needed for things to settle		#* Typically several weeks are needed for things to settle
Line 70:		Line 70:
	#* your project manager will help broker this step for you		#* your project manager will help broker this step for you
	#* the key customers for each feature are identified in the Architectural Features Google spreadsheet		#* the key customers for each feature are identified in the Architectural Features Google spreadsheet
	#* discuss relevant feedback ~~with arch~~@ and revise the architecture as required		#* discuss relevant feedback on the ''lustre-devel'' mailing list@ and revise the architecture as required
	# Cross reference		# Cross reference
	#* Add bugzilla link to architecture pages (in a Reference section at the bottom)		#* Add bugzilla link to architecture pages (in a Reference section at the bottom)