From 5378a840a798c258fed97c3f3bb7804f75654cbd Mon Sep 17 00:00:00 2001 From: Jon Bratseth Date: Tue, 5 Oct 2021 20:17:58 +0200 Subject: Clean up contribution info - Bring links up to date - Separate and flesh out governance - Remove Verizon Media reference - Clean up some language --- CONTRIBUTING.md | 62 +++++++++++++++++++++++++++++++++++++-------------------- GOVERNANCE.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 ++-- 3 files changed, 100 insertions(+), 24 deletions(-) create mode 100644 GOVERNANCE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a86f99d17c..9e18ffbf487 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,7 @@ - + + # 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 @@ + + +# 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 -- cgit v1.2.3