Merge pull request #19425 from vespa-engine/bratseth/contributing-fixesv7.478.19

Clean up contribution info

3 files changed, 100 insertions, 24 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3a86f99d17c..9e18ffbf487 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,5 +1,7 @@
-<!-- Copyright 2017 Yahoo Holdings. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root. -->
+<!-- Copyright Yahoo. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root. -->
+
 # Contributing to Vespa
+
 Contributions to [Vespa](http://github.com/vespa-engine/vespa),
 [Vespa system tests](http://github.com/vespa-engine/system-test),
 [Vespa samples](https://github.com/vespa-engine/sample-apps)
@@ -7,58 +9,74 @@ and the [Vespa documentation](http://github.com/vespa-engine/documentation) are
 This documents tells you what you need to know to contribute.
 
 ## Open development
+
 All work on Vespa happens directly on Github,
 using the [Github flow model](https://guides.github.com/introduction/flow/).
-We release the master branch a few times a week and you should expect it to almost always work.
-In addition to the [public Screwdriver build](https://cd.screwdriver.cd/pipelines/6386)
-we have a large acceptance and performance test suite which
-is also run continuously. We plan to add this to the open source code base later.
+We release the master branch four times a week and you should expect it to always work.
+The continuous build of Vespa is at [https://factory.vespa.oath.cloud](https://factory.vespa.oath.cloud).
+You can follow the fate of each commit there.
 
-All pull requests are reviewed by a member of the Vespa Committers team.
+All pull requests must be approved by a 
+[Vespa Committer](https://github.com/orgs/vespa-engine/people).
 You can find a suitable reviewer in the OWNERS file upward in the source tree from
-where you are making the change (the OWNERS have a special responsibility for
+where you are making the change (OWNERS have a special responsibility for
 ensuring the long-term integrity of a portion of the code).
-If you want to become a committer/OWNER making some quality contributions is the way to start.
 
+The way to become a committer (and OWNER) is to make some quality contributions 
+to an area of the code. See [GOVERNANCE](GOVERNANCE.md) for more details.
 
-***Creating a Pull Request***
+### Creating a Pull Request
 
-Please follow [best practices](https://github.com/trein/dev-best-practices/wiki/Git-Commit-Best-Practices) for creating git commits.
+Please follow 
+[best practices](https://github.com/trein/dev-best-practices/wiki/Git-Commit-Best-Practices) 
+for creating git commits.
 
-When your code is ready to be submitted, [submit a pull request](https://help.github.com/articles/creating-a-pull-request/) to begin the code review process.
+When your code is ready to be submitted, 
+[submit a pull request](https://help.github.com/articles/creating-a-pull-request/) 
+to request a code review.
 
-We only seek to accept code that you are authorized to contribute to the project. We have added a pull request template on our projects so that your contributions are made with the following confirmation:
+We only seek to accept code that you are authorized to contribute to the project. 
+We have added a pull request template on our projects so that your contributions are made 
+with the following confirmation:
 
 > I confirm that this contribution is made under the terms of the license found in the root directory of this repository's source tree and that I have the authority necessary to make this contribution on behalf of its copyright owner.
 
 ## Versioning
+
 Vespa uses semantic versioning - see
 [vespa versions](http://docs.vespa.ai/en/vespa-versions.html).
 Notice in particular that any Java API in a package having a @PublicAPI
-annotation in the package-info file cannot be changed in an incompatible way
-between major versions: Existing types and method signatures must be preserved
+annotation in the package-info, and no @Beta annotation on the class,
+cannot be changed in an incompatible way between major versions: 
+Existing types and method signatures must be preserved
 (but can be marked deprecated).
 
+We verify ABI compatibility during the regular Java build you'll run with Maven (mvn install).
+This build step will also fail if you *add* to public API's, which is fine if there's a good reason
+to do it. In that case update the ABI spec as instructed in the error message.
+
 ## Issues
+
 We track issues in [GitHub issues](https://github.com/vespa-engine/vespa/issues).
 It is fine to submit issues also for feature requests and ideas, whether or not you intend to work on them.
 
-There is also a [ToDo list](TODO.md) for larger things which nobody are working on yet.
+There is also a [ToDo list](TODO.md) for larger things nobody are working on yet.
 
 ## Community
-If you have questions, want to share your experience or help others, please join our community on [Stack Overflow](http://stackoverflow.com/questions/tagged/vespa).
+
+If you have questions, want to share your experience or help others, 
+join our [Slack channel](http://slack.vespa.ai).
+See also [Stack Overflow questions tagged Vespa](http://stackoverflow.com/questions/tagged/vespa),
+and feel free to add your own.
 
 ### Getting started
-See [README](README.md) for how to build and test Vespa.
 
-For an overview of the modules, see [Code-map.md](Code-map.md).
+See [README](README.md) for how to build and test Vespa.
+[Code-map.md](Code-map.md) provides an overview of the modules of Vespa.
 More details are in the READMEs of each module.
 
 ## License and copyright
+
 If you add new files you are welcome to use your own copyright.
 In any case the code (or documentation) you submit will be licensed
 under the Apache 2.0 license.
-
-## Code of Conduct
-
-We encourage inclusive and professional interactions on our project. We welcome everyone to open an issue, improve the documentation, report bug or submit a pull request. By participating in this project, you agree to abide by the [Verizon Media Code of Conduct](Code-of-Conduct.md). If you feel there is a conduct issue related to this project, please raise it per the Code of Conduct process and we will address it.
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
new file mode 100644
index 00000000000..617f2d3c27c
--- /dev/null
+++ b/GOVERNANCE.md
@@ -0,0 +1,58 @@
+<!-- Copyright Yahoo. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root. -->
+
+# Vespa Governance
+
+Anyone is welcome to contribute to Vespa, by [creating pull requests](CONTRIBUTING.md)
+or taking part in discussions about features, e.g in [GitHub issues](https://github.com/vespa-engine/vespa/issues).
+
+This document defines who has authority to do what on the Vespa open source project.
+
+While a formal assignment of authority is necessary as a fallback mechanism, it is
+not the way decisions regarding Vespa are usually made, or expected to be made.
+The community sees disagreement as good as a diversity of perspectives having influence
+leads to better decisions. We seek to resolve disagreement by reaching 
+consensus based on the merit of technical arguments, with no regards to status or
+formal role. This almost always works.
+
+# Vespa roles
+
+There are two formal roles in Vespa:
+
+* __Vespa Committers__ have the right to merge pull requests into the Vespa repo.
+* __The Vespa Board__ has final authority over all decisions made on the project.
+
+# Vespa committers
+
+A __Vespa committer__ is able to merge pull requests into the Vespa repositories under
+[https://github.com/vespa-engine](https://github.com/vespa-engine), including into
+the master branch which is released to production.
+
+To become a Vespa Committer, start making PR's that are approved. When a sufficient
+trust is built through working on Vespa this way, any current Vespa Committer can nominate
+you to the Vespa board for the committer role.
+
+Every pull requests must be approved by a Vespa Committer which is different from the
+author of the request, either by clicking "approve", by making a comment indicating agreement,
+or simply merging it. As a rule, approval should happen before merge, but this is not strictly 
+required as the approver can revert.
+
+The Vespa committers are listed here:
+[https://github.com/orgs/vespa-engine/people](https://github.com/orgs/vespa-engine/people)
+
+# The Vespa board
+
+The __Vespa board__ has final authority over all decisions regarding the Vespa project,
+including 
+
+* whether to merge (or keep) a PR in the event of any dispute, 
+* who should be committers and who should be members of the board, and
+* whether to make any changes to the governance policy (this document).
+
+The board consists of 4 people, and makes decisions by majority vote.
+On a tie the leader of the board has a double vote.
+
+The board members are:
+* Jon Bratseth (bratseth) - leader
+* Kristian Aune (kkraune)
+* Kim Johansen (johans1)
+* Frode Lundgren (frodelu)
diff --git a/README.md b/README.md
index 7d3be172cb5..5c0de9f8202 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ The open big data serving engine - Store, search, organize and make machine-lear
 over big data at serving time.
 
 This is the primary repository for Vespa where all development is happening. 
-New production releases from this repository's master branch are made each weekday from Monday to Thursday.
+New production releases from this repository's master branch are made each weekday from Monday through Thursday.
 
 * Home page: [https://vespa.ai](https://vespa.ai)  
 * Documentation: [https://docs.vespa.ai](https://docs.vespa.ai)  
@@ -50,7 +50,7 @@ Or deploy your Vespa applications to the cloud service: [https://cloud.vespa.ai]
 - Explore the [sample applications](https://github.com/vespa-engine/sample-apps/tree/master)
 - Follow the [Vespa Blog](https://blog.vespa.ai/) for feature updates / use cases
 
-Full documentation is available on [https://docs.vespa.ai](https://docs.vespa.ai).
+Full documentation is at [https://docs.vespa.ai](https://docs.vespa.ai).
 
 
 ## Contribute