WARNING: This is the _old_ Lustre wiki, and it is in the process of being retired. The information found here is all likely to be out of date. Please search the new wiki for more up to date information.

Difference between revisions of "Architecture - Writing Architecture Documents"

From Obsolete Lustre Wiki
Jump to navigationJump to search
 
m (Protected "Architecture - Writing Architecture Documents" ([edit=sysop] (indefinite) [move=sysop] (indefinite)))
 
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
Lustre Architecture Process
+
This page provides some guidelines for preparing architecture documents.
  
 
== 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
+
* Good example of a feature architecture - [[Architecture - Simple_Space_Balance_Migration|Simple Space Balance Migration]]
* Lustre Architectural Features Google spreadsheet -  http://spreadsheets.google.com/a/clusterfs.com/ccc?key=pMf3Udi56jKwFpCMJDq-Mbg&hl=en
 
* Good example of a feature architecture - [http://arch.lustre.org/index.php?title=Simple_Space_Balance_Migration Simple Space Balance Migration]
 
* Task Planning Worksheet form - https://wikis.clusterfs.com/intra/index.php/Task_Planning_Work_Sheets
 
  
 
== General Guidelines ==
 
== General Guidelines ==
* Discuss everything on arch@; 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)
* 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 - [http://arch.lustre.org/index.php?title=Simple_Space_Balance_Migration Simple Space Balance Migration]
+
** Summary QAS features - [[Architecture - Simple_Space_Balance_Migration|Simple Space Balance Migration]]
** Detailed QAS - [http://arch.lustre.org/index.php?title=QAS_Timeouts Adaptive Timeouts]
+
** Detailed QAS - [[Architecture - Adaptive Timeouts - Use Cases|Adaptive Timeouts]]
** Definition lists - [http://arch.lustre.org/index.php?title=Simple_Space_Balance_Migration Simple Space Balance Migration]
+
** Definition lists - [[Architecture - Simple_Space_Balance_Migration|Simple Space Balance Migration]]
  
 
== Process Outline ==
 
== Process Outline ==
Line 24: 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
Line 44: 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 50: 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 67: 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 73: 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)
Line 82: Line 79:
  
 
Example Architectures
 
Example Architectures
* http://arch.lustre.org/index.php?title=Simple_Space_Balance_Migration
+
* [[Architecture - Simple_Space_Balance_Migration|Simple Space Balance Migration]]
* http://arch.lustre.org/index.php?title=QAS_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
 

Latest revision as of 16:52, 20 January 2010

This page provides some guidelines for preparing architecture documents.

Resources

  • SEI books - Documenting Software Architectures, Software Architecture in Practice
  • 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.
  • Good example of a feature architecture - Simple Space Balance Migration

General Guidelines

  • 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)
  • Take care with formatting, make them look nice -- people can read these all over
  • Use consistent formatting:

Process Outline

  1. Get your architecture assignments and priorities from the Lustre Architectural Feature Google spreadsheet
    • this page is maintained by the Chief Architect and VP engineering
    • the Responsible Architect(s) column
      • identifies who needs to generate the architecture
      • 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 others architects are responsible for contributing to the design
    • the "link" column identifies the page on the Lustre Architecture wiki were you work should be published
  2. Make a list of summary requirements, using line per row, and an indicator what kind of use case they are. There are templates and patterns to aid you in finding solutions.
    1. quality attribute scenarios, focus on the following six attributes.
      • performance
      • availability
      • testability
      • modifiability
      • usability
      • security
    2. features
    3. implementation constraints
    4. Examples:
      • features - e.g. offer posix interface for this or that, or replicate file systems, but not atime
      • qualities - e.g. provide performance of 90% of hardware, propagate changes within 1 sec, recovery without semantic changes to clients
      • implementation constraints - e.g. use POSIX DMU, or use existing llog code, or use replication code from cmd2
    5. document this on your assigned architecture wiki page. If there are many, start a separate QAS page
  3. Review use cases with Chief Architect and architecture team
    • 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
  4. Review use cases with key customers
    • your project manager will help broker this step for you
    • 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?
    • discuss relevant feedback on the lustre-devel mailing list and revise use cases as required
  5. Decompose the problem into a more detailed architectural definition
    • almost all architecture starts by decomposing the problem
    • 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.
    • it is pretty important that the decomposition leaves no doubt about what happens where
  6. Write detailed behavioral architecture
    1. Write detailed attribute scenarios
      • pick the hardest use cases from the table
      • describe in more detail what happens when they take place, for each of the components you have identified in the decomposition phase
      • Use existing template tables from the example pages
    2. Sequence and State Diagrams
      • Use UML2 notation - see the petascale white paper for some examples
      • for example, "what is the RPC pattern to handle a lock revocation"
    3. Write detailed command invocations
      • use cases can contain exact command invocations: type mkfs.lustre --mds ...... (all arguments ) to achieve ......
  7. Review architecture with architecture team
    • 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.
    • Typically several weeks are needed for things to settle
  8. Review architecture with key customers
    • your project manager will help broker this step for you
    • 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
  9. Cross reference
    • Add bugzilla link to architecture pages (in a Reference section at the bottom)
    • Add an architecture link to the planning worksheet
  10. Finish up by preparing the task planning worksheet (which has its own process)

Examples

Example Architectures