* Google Docs is not a "code-oriented" tool, like asciidoc can be
* Review in Google Docs is not as simple as a PR code review in GitHub

## Decision

The *Build Tool Team* has decided to use Architectural Decision Records (aka ADR) to track decisions we want to follow.

The main logic with ADRs is to describe (architectural) decisions made:

    <groupId>parent-version-range-local</groupId>
    <artifactId>parent</artifactId>
    <version>[1,10]</version>
  </parent>
  <artifactId>child</artifactId>
  <version>${revision}</version>
  <packaging>pom</packaging>
  <properties>
    <revision>1.0-SNAPSHOT</revision>
  </properties>

  <parent>
    <groupId>org.apache</groupId>
    <artifactId>apache</artifactId>
    <version>[1,1]</version>
  </parent>
  <artifactId>child</artifactId>
  <version>${revision}</version>
  <packaging>pom</packaging>
  <properties>
    <revision>1.0-SNAPSHOT</revision>
  </properties>

! stdout .

# Fetching a nonexistent commit should return an "unknown revision"
# error message.
! go mod download github.com/golang/term@86186f3aba07ed0212cfb944f3398997d2d07c6b
stderr '^go: github.com/golang/term@86186f3aba07ed0212cfb944f3398997d2d07c6b: invalid version: unknown revision 86186f3aba07ed0212cfb944f3398997d2d07c6b$'
! stdout .

! go mod download github.com/golang/nonexist@master

 * http://creativecommons.org/publicdomain/zero/1.0/
 */

/*
 * Source:
 * http://gee.cs.oswego.edu/cgi-bin/viewcvs.cgi/jsr166/src/jsr166e/extra/AtomicDoubleArray.java?revision=1.5
 * (Modified to adapt to guava coding conventions and
 * to use AtomicLongArray instead of sun.misc.Unsafe)
 */

package com.google.common.util.concurrent;

import static java.lang.Double.doubleToRawLongBits;

                }

                return sid.revision == this.revision;
            }
        }
        return false;
    }


    /**
     * Return the numeric representation of this sid such as
     * <tt>S-1-5-21-1496946806-2192648263-3843101252-1029</tt>.
     */
    @Override
    public String toString () {
        String ret = "S-" + ( this.revision & 0xFF ) + "-";

	"io"
	"os"
	"path"
	"path/filepath"
	"strconv"
	"time"

	"cmd/go/internal/base"
)

func svnParseStat(rev, out string) (*RevInfo, error) {
	var log struct {
		Logentry struct {
			Revision int64  `xml:"revision,attr"`
			Date     string `xml:"date"`
		} `xml:"logentry"`
	}
	if err := xml.Unmarshal([]byte(out), &log); err != nil {
		return nil, vcsErrorf("unexpected response from svn log --xml: %v\n%s", err, out)
	}

! go list -m golang.org/x/time@334d83c35137ac2b376c1dc3e4c7733791855a3a # refs/changes/24/41624/3
stderr 'unknown revision'
! go list -m golang.org/x/time@v0.0.0-20170424233410-334d83c35137
stderr 'unknown revision'
! go list -m golang.org/x/time@334d83c35137
stderr 'unknown revision'

-- go.mod --

cd ..
! go list -m golang.org/x/text
stderr 'golang.org/x/text@v0.2.1-0.20170915032832-14c0d48ead0c: invalid pseudo-version: revision 14c0d48ead0c is not a descendent of preceding tag \(v0.2.0\)'

# A pseudo-version derived from a canonical tag on the same revision is invalid.
cp go.mod.orig go.mod

## Architecture Standards

**Experimental!**

We'd like to capture our architectural decisions about the build tool as [Architectural Decision Records (ADRs)](https://adr.github.io/).
For now we just have this global repository of ADRs.
If we see fit, we can break these out to per-platform ones, or keep a hybrid approach to having global and platform-specific ADSs.

Our aim is to keep the process lightweight and approachable.