← Back to branch summary

~nskaggs/+junk/juju-packaging-test

« back to all changes in this revision

Viewing changes to src/github.com/juju/juju/core/doc.go

  • Committer: Nicholas Skaggs
  • Date: 2016-10-27 20:23:11 UTC
  • Revision ID: nicholas.skaggs@canonical.com-20161027202311-sux4jk2o73p1d6rg
Re-add src

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/github.com/juju/juju/core/doc.go
 
1
// Copyright 2015 Canonical Ltd.
 
2
// Licensed under the AGPLv3, see LICENCE file for details.
 
3
 
 
4
/*
 
5
Package core exists to hold concepts and pure logic pertaining to juju's domain.
 
6
We'd call it "model code" if we weren't planning to rename "environ" to "model";
 
7
but that'd be quite needlessly confusing, so "core" it is.
 
8
 
 
9
This is a necessarily broad brush; if anything, it's mmost important to be aware
 
10
what should *not* go here. In particular:
 
11
 
 
12
  * if it makes any reference to MongoDB, it should not be in here.
 
13
  * if it's in any way concerned with API transport, or serialization, it should
 
14
    not be in here.
 
15
  * if it has to do with the *specifics* of any resource *substrate* (compute,
 
16
    storage, networking, ...) it should not be in here.
 
17
 
 
18
...and more generally, when adding to core:
 
19
 
 
20
  * it's fine to import from any subpackage of "github.com/juju/juju/core"
 
21
  * but *never* import from any *other* subpackage of "github.com/juju/juju"
 
22
  * don't you *dare* introduce mutable global state or I will hunt you down
 
23
  * like a dog
 
24
 
 
25
...although, of course, *moving* code into core is great, so long as you don't
 
26
drag in forbidden concerns as you do so. At first glance, the following packages
 
27
are good candidates for near-term corification:
 
28
 
 
29
  * constraints (only dependency is instance)
 
30
  * instance (only dependency is network)
 
31
  * network (already core-safe)
 
32
  * watcher-excluding-legacy (only depends on worker[/catacomb])
 
33
  * worker/catacomb
 
34
  * worker/dependency
 
35
  * worker-excluding-other-subpackages
 
36
 
 
37
...and these have significant core-worthy content, but will be harder to extract:
 
38
 
 
39
  * environs[/config]-excluding-registry
 
40
  * storage-excluding-registry (depends only on instance and environs/config)
 
41
  * workload
 
42
 
 
43
...and, last but most, state, which deserves especially detailed consideration,
 
44
because:
 
45
 
 
46
  * it is by *far* the largest repository of business logic.
 
47
  * much of the business logic is horribly entangled with mgo concerns
 
48
  * plenty of bits -- pure model validation bits, status stuff, unit/machine
 
49
    assignment rules, probably a thousand more -- will be easy to extract
 
50
 
 
51
...but plenty of other bits will *not* be easy: in particular, all the business
 
52
rules that concern consistency are really tricky, and somewhat dangerous, to
 
53
extract, because (while those rules and relationshipps *are* business logic) we
 
54
need to be able to *render* them into a mgo/txn representation to ensure DB
 
55
consistency. If we just depend on implementing the state bits to match, rather
 
56
than *use*, the core logic, we're basically completely screwed.
 
57
 
 
58
The one place we address these concerns is in the core/lease.Token interface,
 
59
which includes functionality for communicating with the implementation of
 
60
lease.Client currently in play; where the state code which is responsible for
 
61
creating a mongo-based client is not entirely unjustified in making use of the
 
62
trapdoor to extract mgo.txn operations from lease.Token~s passed back in.
 
63
 
 
64
There's probably some sort of generally-useful abstraction to be extracted there,
 
65
but I'm not sure what it is yet.
 
66
*/
 
67
package core