Header Improvements (File description and scope)

[krisnova]

Would like to propose a format to start including descriptive headers in kops code.

Digging into kops is fun, but I am constantly referencing my notes as I explore the code base.

I think it would be helpful to store descriptions and code docs in the files themselves. Not a hard requirement, but it would be nice to have an agreed upon format and blessing to start doing this if an engineer so desires

/*
Copyright 2016 The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

NOTES GO HERE
Holds logic that will <something>. 
This code connects <other pieces> and solves <problem>
etc, etc, etc
NOTES GO HERE

*/

Thoughts?

[chrislovecnm]

We actually have a standard on the use of a proper license header that needs to be documented ... We need the boilerplate block to make the K8s lawyers happy, to be able to run the header checker that I have.

Another code block afterward I think is awesome.

See:

https://github.com/kubernetes/kops/tree/master/hack/boilerplate

[krisnova]

Makes sense..

/*
Copyright 2016 The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
/*
NOTES GO HERE
Holds logic that will <something>. 
This code connects <other pieces> and solves <problem>
etc, etc, etc
NOTES GO HERE
*/

This works for me

[chrislovecnm]

FYI -

$ hack/verify-boilerplate.sh
Boilerplate header is wrong for: /Users/clove/Workspace/src/k8s.io/kops/cloudmock/aws/mockec2/api.go
Boilerplate header is wrong for: /Users/clove/Workspace/src/k8s.io/kops/cloudmock/aws/mockec2/routetable.go
Boilerplate header is wrong for: /Users/clove/Workspace/src/k8s.io/kops/cloudmock/aws/mockec2/unimplemented.go

# false positive from  hack/verify-boilerplate.sh, not sure if we need header
Boilerplate header is wrong for: /Users/clove/Workspace/src/k8s.io/kops/federation/model/bindata.go
Boilerplate header is wrong for: /Users/clove/Workspace/src/k8s.io/kops/upup/models/bindata.go

We need to figure out the auto gen code because it does not have a header.

We need this in our CI