Add: more content

7 files changed, 418 insertions, 0 deletions

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: <https://www.debian.org/Bugs/>.
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]]):
+
+<div class="newslist">
+[[!inline pages="page(blog/*) and tagged(meeting)" 
+  limit=3 template=titlepage archive=yes trail=no feeds=no]]
+</div>