From 5d33aa0122816ab8eaae95c0a8c49d3c75c42614 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 8 Sep 2018 13:05:17 +0300 Subject: Add: more content --- blog.mdwn | 9 ++++ conduct.mdwn | 75 ++++++++++++++++++++++++++ governance.mdwn | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ issues.mdwn | 4 ++ patches.mdwn | 79 ++++++++++++++++++++++++++++ pm.mdwn | 62 ++++++++++++++++++++++ project.mdwn | 29 ++++++++++ 7 files changed, 418 insertions(+) create mode 100644 blog.mdwn create mode 100644 conduct.mdwn create mode 100644 governance.mdwn create mode 100644 issues.mdwn create mode 100644 patches.mdwn create mode 100644 pm.mdwn create mode 100644 project.mdwn diff --git a/blog.mdwn b/blog.mdwn new file mode 100644 index 0000000..3ff4fd8 --- /dev/null +++ b/blog.mdwn @@ -0,0 +1,9 @@ +[[!meta title="Development blog"]] + +This is the **development** blog for vmdb2. It is meant to be a +communication channel for those interested in the development of vmdb2 +itself. + +This page collects all the blog entries in one page. Just the titles. + +[[!inline pages="page(blog/*)" archive=yes trail=yes]] diff --git a/conduct.mdwn b/conduct.mdwn new file mode 100644 index 0000000..5e258f1 --- /dev/null +++ b/conduct.mdwn @@ -0,0 +1,75 @@ +[[!meta title="Code of conduct"]] + +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, race, +religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at ick-conduct@pieni.net (see [contact](https://ick.liw.fi/contact/)). All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org diff --git a/governance.mdwn b/governance.mdwn new file mode 100644 index 0000000..b2700ab --- /dev/null +++ b/governance.mdwn @@ -0,0 +1,160 @@ +[[!meta title="Governance"]] + +vmdb2 constitution v1.0 +============================================================================= + +Introduction +----------------------------------------------------------------------------- + +This constitution is the formal rules of the vmdb2 project: it defines +how we govern the project. The vmdb2 project develops the vmdb2 software, +for Debian image building. The project governance structure is +informally based on the principle of **do-ocracy**: those who do, +decide. This constitution formalises the principle, to help the +project grow, to make it easier for new contributors to join the +project, and to avoid misunderstandings. + +This is the first version of the constitution. It is expected to grow +as the project gets more contributors. A probable change is to start +using a [Debian-style Condorcet][] voting method. It is overkill with +only a handful of contributors, but will become more important later +on. + +[Debian-style Condorcet]: https://www.debian.org/vote/ + + +Levels of membership +----------------------------------------------------------------------------- + +There are two levels of membership in the project: **contributors** +and **voting members**. Contributors are all those who work to the +project in order to make the vmdb2 software, its website, documentation, +other deliverables, or the project itself better. Voting members have +the power to collectively make any decision of the project by voting +on it. + +**Voting members are chosen by voting.** Candidates are nominated by +themselves or by voting members, with approval of candidate. Voting +membership may not be inflicted upon anyone without their **explicit +approval**. + +Voting membership may be revoked by a vote. + +No contributors or voting member is required to do work for the +project, and the project cannot compel anyone to do anything. The +project may, via a formal decision, forbid something from being done +in the context of a project, or require that if a thing is done, it +gets done in a particular way. + + +Decision making +----------------------------------------------------------------------------- + +Most decisions in the project are made by contributors as part of the +work they do to contribute. These are called **mundane decisions**, +and include things like how to structure a piece of code or +documentation, how to name some component, etc. Mundane decisions do +not normally need to be documented formally, but can be, if a +contributor thinks it useful. + +If a mundane decision is challenged, the project aims to find a +**rough consensus** on the matter via discussion. This is called a +**consensus decision**. Consensus decisions are documented on a +project website, and marked as such. + +To make rough consensus easier to achieve, the project follows the +[lazy consensus][] approach. If you don't think a change is +controversial, just do it. We use version control, changes are easy to +revert. If you're not entirely sure, announce that you're going to +make the change in three days, which gives everyone time to object. + +[lazy consensus]: https://rave.apache.org/docs/governance/lazyConsensus.html + +If consensus is not reached, or is challenged by a voting member, the +project will **vote** on the matter. This is called a **formal +decision**. Formal decisions are documented on a project website, and +marked as such. + + +Voting procedure +----------------------------------------------------------------------------- + +The **project secretary** is chosen by voting by the voting members +from among the voting members. The secretary must themselves be a +voting member for the duration of their term. Candidates nominate +themselves, or by other voting members with the candidate's approval. +The secretary has the duty to conduct votes in a suitable manner. +Votes are decided by **simple majority**, and voting members have an +**equal vote**. In case of a tie, the project secretary casts the +decisive vote. + +Voting members may suggest options for the ballot. The secretary +decides what the ballot should be, announces the vote on a suitable +project forum, and declares how a vote is to be cast. The **voting +period is 7 days**. The secretary receives votes, counts them, and +announces the result, and documents the decision on the project +website. **Votes are made public** at that time, if not earlier. + + +Team delegations +----------------------------------------------------------------------------- + +Responsibility of making decisions about an area or aspect of the +project may be **delegated to a team** by a vote among the voting +members. The decision shall name all members of the team and the scope +of the delegation. The team members may be any contributors, not just +formal members. Decisions within the team are made in the same manner +as by the project as a whole, with contributors voting as if they were +voting members. The team's consensus and formal decisions shall be +documented in the same way as project decisions. The project may +override a team's decision via project vote. + + +Time and term limitations +----------------------------------------------------------------------------- + +Voting membership and the position of secretary and team delegations +are **time limited**, and **expire automatically** with no further +action. Memberships expire one by one in order of earliest membership +first. The last membership does not expire, as that would leave the +project without voters. If the project only has one voting member, +that member is automatically also the secretary. + +The point of the automatic expiration is to avoid having inactive +former contributors as voting members indefinitely. + +The **terms end on the following dates**, except terms do not end +automatically within their first three months: + +- voting membership ends September 1 +- position of secretary ends March 1 +- team delegations ends June 1. + +On each date, the term ends at 23:59:59 in the UTC time zone. + +Voting membership, secretaryship, and team delegation may be renewed +by a vote. There is no limit on how many times renewal may happen. + +Voting membership gets automatically renewed if the member has voted +at least once in the preceding 12 months. + +It is the duty of the secretary to arrange new votes to renew terms in +time before the terms end, and to maintain a list of voting +memberships. + + +Status +----------------------------------------------------------------------------- + +The current project secretary is Lars Wirzenius. + +The complete list of voting members in the project (in order of +joining): + +* Lars Wirzenius (expires 2019-09-01) + +See also: + +* list of [[consensus decisions|tag/consensus-decision]]. +* list of [[formal decisions|tag/formal-decision]]. +* list of [[votes|tag/vote]]. diff --git a/issues.mdwn b/issues.mdwn new file mode 100644 index 0000000..e5d705f --- /dev/null +++ b/issues.mdwn @@ -0,0 +1,4 @@ +[[!meta title="Issues"]] + +To report an issue with vmdb2, please file a bug using the Debian bug +tracker: . diff --git a/patches.mdwn b/patches.mdwn new file mode 100644 index 0000000..4f5b035 --- /dev/null +++ b/patches.mdwn @@ -0,0 +1,79 @@ +[[!meta title="Sending patches to vmdb2"]] + +vmdb2 is a free software project and has an associated website. This +page explains how you can contribute changes to either. + +[git]: https://git-scm.com/ +[git.liw.fi]: http://git.liw.fi/ +[vmdb2]: http://git.liw.fi/vmdb2/ +[vmdb2.liw.fi]: http://git.liw.fi/vmdb2.liw.fi +[Gitano]: https://www.gitano.org.uk/ +[free software should use free tools]: https://mako.cc/writing/hill-free_tools.html + +We use the [git][] version control system. Our repositories are hosted +on a [git.liw.fi][], a personal server hosted by Lars Wirzenius, using +the [Gitano][] software. See the [vmdb2][] and [vmdb2.liw.fi][] +repositories. + +We don't use GitHub, as it runs proprietary +software, and [free software should use free tools][]. We also don't +use one of the free software implementations that are similar to +GitHub, because we prefer Gitano, and some of us don't enjoy the +pull-request style of accepting contributions that GitHub has. +However, we're happy to get changes from GitHub, or any other git +server, over an open protocol. + +Despite our aversion toward GitHub and pull requests, we want to make +it easy for you to send us patches. + +Here's a few ways you can send us changes: + +* Tell us in your own free words what the proposed change is, over + e-mail or another medium. We can do the change in git ourselves, if + we agree to the change. This is good for small changes, such as + wording changes, or such. + + If you don't know how to use git, use this method. It's low tech, + but also low friction to you, even if a little more work for us. + +* Send us changes formatted with "git format-patch", over email to + liw@liw.fi. (Using "git send-email" is good, too.) + + If you're sending a patch series consisting of several patches, + add a "cover letter" that expolains what the whole series is about. + +* Make the changes available on a different git server, and send us a + URL we can pull from. You can use GitHub or any other server that's + convenient for you. You can even create a pull request and send a + URL to that. + + +# On patches (and pull requests) + +We prefer a patch series and pull request to tell a story of the +change that is easy to follow and review and understand. + +* Each patch/commit should have a clear commit message. The commit + message should explain why the change is made, and not just repharse + the diff. The commit message should stand on its own, as it will be + read on its own in the future, when someone is debugging the + program, possibly with "git bisect". + +* The commit message should follow the [this guide][], and + additionally the first summary line should start with one of the + words "Add", "Change", "Drop", or "Refactor". + +* Each patch/commit should change only one logical thing at a time. It + should also not be semantically large: avoid changing many parts of + the code at once, unless it's trivial changes like renaming a class. + Do such renames in a patch/commit that makes no other changes. + +* Don't squash commits into one for a pull request. + +* If necessary, clean up the branch/pull request with "git rebase -i" + to produce something that's clear and easy to review. + +* Remember to update the NEWS file for any changes visible to the user + or system administrator. + +[this guide]: https://chris.beams.io/posts/git-commit/ diff --git a/pm.mdwn b/pm.mdwn new file mode 100644 index 0000000..98cc24f --- /dev/null +++ b/pm.mdwn @@ -0,0 +1,62 @@ +[[!meta title="Project management"]] + +This page describes the lightweight project management process for +development of vmdb2. Participation is voluntary. + +Iterative development process +============================================================================= + +Iterative development seems to be the only thing that makes sense in +order to produce working software that fills what users actually need. +Otherwise, you don't get any feedback until at the end of the +development period, when things should already be mostly finished. +With iterations, you do a little bit of work, show that to relevant +people, get feedback, and incorporate the feedback to future work as +seems most sensible. + +There's a ton of methodologies to do iterative development. Scrum is +currently popular. However, vmdb2 needs to be fun, and Scrum seems too +heavy-weight for fun. Instead, this nearly informal process is what +[[people/liw]] wants to use. + +* Iterations are a calendar week. + +* Start iteration with a short planning meeting, where goals are + discussed and decided upon, and tasks outlined, and everything's + written down. The tasks should be specified with a clear scope, and + with enough detail to estimate that they can be done. Large tasks + should be split down into small tasks, preferably into tasks less + than an hour each. + + Only allocate enough tasks that they can all be completed with a + high likelihood. It's always OK to do more, but it's de-moralising + to never complete everything. + +* End the iteration with a short retrospective meeting, to summarise + what was done (from the planned list of tasks or otherwise), and + reflecting on the process to improve it, as necessary. + +* Write down decisions, in a meeting note in the intrawiki blog. + +* Estimates are done by the person who'll be doing the work. They + should not be optimistic. + +Development workflow +============================================================================= + +* Work should be done in feature branches, but merged frequently to + master. Unfinished features should be disabled, via some sort of + feature toggle. Merging branches only after a long time means + there's more pain during merge, and it takes longer until there's + feedback on the changes in the branch from, say, CI, actual use, or + code review. + +* Work for Heat/Ansible stuff should also be merged frequently, and + any affected production systems (`infra-*` stacks) should be + deployed after merge is done. The master branch and what actually + runs in production should never be far apart. + +* Merging should ideally involve review. However, as there's only the + one actually working on vmdb2, review would slow things down too much. + Thus, we'll probably not have review for the time being. (Hint: + contributing reviews would be a useful thing to do.) diff --git a/project.mdwn b/project.mdwn new file mode 100644 index 0000000..4fa140c --- /dev/null +++ b/project.mdwn @@ -0,0 +1,29 @@ +[[!meta title="Project"]] + +vmdb2 is a community project: it is developed by some people who want +to do it. You could help! + +Information on how we do things, and help to get you started if you're +interested: + +* Project [[governance]]. + * [[Code of conduct|conduct]] +* [[Process description|pm]] + * [[Current and past projects|projects]] +* [[Development blog|blog]] (see [[feeds|blog_feed]] also). + * [[consensus decisions|tag/consensus-decision]]. + * [[formal decisions|tag/formal-decision]]. + * [[votes|tag/vote]]. +* [[Issue (bug) tracking|issues]] +* [[Sending patches|patches]] or pull requests. + +Please note that this project is released with a [[Contributor Code of +Conduct|conduct]]. By participating in this project you agree +to abide by its terms. + +Minutes from the latest meetings (see more in [[blog]]): + +
+[[!inline pages="page(blog/*) and tagged(meeting)" + limit=3 template=titlepage archive=yes trail=no feeds=no]] +
-- cgit v1.2.1