opendev/system-config
Code Issues Proposed changes

Polish the main opendev.org page

Browse Source 
This change represents a number of edits originally suggested in
review comments on Idaefb41590df24e649a4fd5225cc1078f2903696 as well
as a general re-edit of some of the sections for improved accuracy
and flow.

Change-Id: I2806e8099f44c43c161cac51872a712e8ee128e8
This commit is contained in:
Jeremy Stanley 2021-01-07 20:15:16 +00:00
parent 9b81846098
commit 32484dade2
1 changed files with 90 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

171
docker/gitea/custom/templates/home.tmpl
View File

@ -26,101 +26,110 @@
<div class="ui stackable middle very relaxed page grid">
<div class="sixteen wide left aligned centered column">
<h2 id="what-is-opendev">What is Opendev?</h2>
<p>OpenDev is a space enabling collaborative Open Source
software development at a huge scale. It is centered around code hosting,
code review, and continuous integration, provided exclusively through
open source solutions like Git, Gitea, Gerrit and Zuul. It also provides
a number of peripheral collaboration services (like an etherpad instance for
collaborative text editing). All Opendev services are openly operated by the
Opendev community, and continuously integrated and deployed using Opendev
itself.</p>
<h2 id="what-is-opendev">What is OpenDev?</h2>
<p>OpenDev is a collaboratory for open source software
development at scale. Its focus is on code review, continuous
integration, and project hosting provided exclusively through open source
solutions like Git, Gerrit, Zuul, and Gitea. It also provides a number of
peripheral collaboration services (like Mailman mailing lists, IRC bots for
notifications and annotating text-based meetings, Jitsi-Meet for
videoconference discussions integrated with Etherpad for collective text
editing). All of these services are openly operated by the community, and
continuously integrated and deployed using OpenDev itself.</p>
<h2 id="opendev-is-different">How is development different with Opendev</h2>
<p>Opendev is not using a pull request (or merge request)
workflow, as implemented by GitHub or Gitlab. It follows a change proposal
workflow, which results in a slightly different experience.</p>
<p>In a pull request workflow, contribution starts by
forking the original repository to your personal repositories, cloning that
repository locally, iterating on development while pushing commits to the
remote repository regularly... until your code seems ready to merge, at
which point you ask the service to create a pull request between your branch
and the original repository. The pull request is reviewed, and if accepted
your changes get merged into the original repository.</p>
<p>In Gerrit, contribution starts by cloning the original
repository locally. You iterate on development, then use git push (or the
git-review tool) to propose your change to Gerrit. The change is reviewed,
and if accepted your change gets merged into the original repository.</p>
<h2 id="opendev-is-different">How is development different with OpenDev</h2>
<p>OpenDev doesn't use a pull request (or merge request)
workflow, like those implemented by GitHub or Gitlab. Instead it follows
Gerrit's iterative change proposal workflow, which results in a slightly
different experience.</p>
<p>In GitHub or Gitlab, contribution typically starts by
forking a personal copy of the original repository, cloning that locally, and
pushing one or more commits to that personal fork. Once your code seems ready
to merge, you ask the service to create a pull request for your branch into the
original repository. The pull request is reviewed, and if accepted your changes
get merged into the original repository. If not, you push more commits to your
fork and update the request seeking more reviews.</p>
<p>By contrast, contribution with Gerrit starts by cloning
the original repository locally. You iterate on development of one or more
local commits, and then use git push (or the git-review tool) to propose your
commits as a series of changes to the Gerrit code review service. Each change
in the series is reviewed, and if it's accepted (and passing tests) then it
gets merged into the original repository. If more work is needed, you amend
the same commits and push new versions of them for re-review.</p>
<p>The difference is subtle, but significant. In the
pull-request model, you create a fork of the original repository, push
pull request model, you create a fork of the original repository, push
changes to it, and ultimately propose to merge changes back. In the change
model, you prepare a change, and propose it. You do not create a fork and
everyone contributes to the same original repository. It generally results
in less fragmentation, and avoids confusion between the original repository
and its numerous forks.</p>
proposal model, you prepare a change, and propose it. You do not create a
complete fork and everyone contributes into the same original repository with
what are basically lightweight, ephemeral topic branches. It results in less
fragmentation overall, and avoids confusion between the original repository and
its numerous forks.</p>
<p>That high-level difference also affects lower-level
details. A pull request may contain several commits, and if merged all those
commits will appear in the original repository history. In Gerrit, every commit
will result in a separate change for code reviewers to review, so developers
usually squash commits created while developing but which do not help
reviewers understand the proposed change. It generally results in easier
code review, and a cleaner git log as meaningful commit messages are
reviewed as part of the change.</p>
<p>In summary, the Gerrit workflow, its user experience
and UI are different from the pull request workflow. While it may not be
immediately familiar to developers used to pull request workflows, it's
worth learning. Its long-term benefits outweigh the short-term drawback
of having to learn a new tool, especially if you are going to spend a lot
of time developing for that project anyway.</p>
is a separate change (optionally depending on other related changes) for code
reviewers to review, so developers squash or amend edits made while developing
to represent the desired final state of that change. Each prior revision of a
change is still retained by the service, as are all the review comments, so
updates can be compared side-by-side for a clear picture of how the change
evolved. It generally results in easier code review, but also a cleaner branch
history with the commit messages reviewed as an integral part of each
change.</p>
<p>In summary, the Gerrit workflow, its user experience and
UI are different from the pull request workflow. While it may not be
immediately familiar to developers used to pull request workflows, it's worth
learning. Long-term benefits outweigh the short-term cost of having to learn a
new tool, especially for someone who is going to spend a lot of time developing
for that project anyway.</p>
<h2 id="integrated-ci">Integrated Continuous Integration</h2>
<p>One key benefit of Opendev is that it integrates
<p>One key benefit of OpenDev is that it integrates
powerful continuous integration features, made possible by the donation of
compute resources from our infrastructure partners. Test jobs are
compute resources from our generous infrastructure partners. Test jobs are
run when changes are proposed and provide code reviewers with valuable
information. Test jobs also run again at merge-time, in case recently-approved
changes introduce an incompatibility. This, combined with the fact that
changes must pass tests before they can be approved, prevents
merging broken code.</p>
information. Test jobs also run again at merge time, in case recently approved
changes introduce an incompatibility, preventing code which doesn't pass tests
from merging to the repository.</p>
<p>Advanced Zuul features like speculative execution of
tests allows changes to test in parallel, so development velocity is
never limited by how thorough you want your tests to be. Changes in one git
repository can depend on proposed changes in another repository, allowing
integration testing of features actively developed across multiple projects,
removing artificial barriers between development teams.</p>
tests allow the testing of sequenced changes in parallel, so development
velocity is rarely limited by how thorough you want your tests to be. Changes
in one Git repository can depend on proposed changes in another repository,
allowing integration testing of features actively developed across multiple
projects, removing artificial barriers between development teams.</p>
<p>This advanced continuous integration system was
developed to sustain the complexity and scale of OpenStack development, one
of the 3 most actively developed open source projects in the world. Opendev
makes this system available to other projects -- enabling open development
at a huge scale for everyone.</p>
developed to sustain the complexity and scale of OpenStack development, one of
the three most actively developed open source projects in the world. OpenDev
makes this system available to other projects, enabling open development at
scale for everyone.</p>
<h2 id="free-tools">Free software needs free tools</h2>
<p>Finally, another key difference between Opendev and
<p>Finally, another key difference between OpenDev and
other development infrastructure services like GitHub or Gitlab.com is that
it's built purely using open source software. GitHub and Gitlab.com are free
to use for open source projects, but they are both using proprietary code.
If your free and open source software requires proprietary code to be built,
is it really free?</p>
<p>It is widely-accepted today that using open source
technology in your software stacks reduces your dependency to third-parties
and allows to spread innovation. It should be obvious that writing software
using open source technology has the same effect. Nothing prevents a service
provider from changing its service terms, creating new limitations or even
fully excluding your project, or contributors from specific countries.
Proprietary development services create the same form of hard limits, lock-in
and dependency than proprietary software does, and prevent open innovation
in the development infrastructure space.</p>
<p>Opendev is entirely built using open source software,
but goes one step beyond: it is also openly operated. All its operation and
configuration is also open source, lives in git, and is continuously-deployed.
In the spirit of open source, it is easy to study, replicate, modify and
redistribute. Like free and open source software, it requires engaging with
its community to get the most of it -- it's not a service you consume, it's
a community you join. That can be a bit overwhelming if you just want to
focus on development, especially when ready-to-consume services are
available. But it's worth it, especially if you want to have a say on what
services are provided, or just support the idea of improving open source
tools in that space.</p>
it's built purely using open source software. GitHub and Gitlab.com are
provided free of charge for open source projects, but they are both implemented
using proprietary code. If development of your free and open source software
requires interaction with proprietary code, is it truly free (as in
freedom)?</p>
<p>It is widely accepted today that using open source
technology reduces your reliance on outside parties and enables innovation. It
should be obvious that developing software by using open source toolchains has
the same effect. Nothing prevents a service provider from changing its terms of
service, creating new limitations, blocking access for contributors connecting
from specific countries, or even fully removing your project. Proprietary
development services create the same form of hard limits, lock-in and
dependency that proprietary software does, and prevent open innovation in the
development infrastructure space.</p>
<p>OpenDev is entirely built using open source software,
but goes one step beyond: it is also openly operated. Even its operation
tooling and configuration is open source, lives in Git, and is
continuously-deployed. It serves as a clear example of transparent
collaboration for systems administration. Like free and open source software,
it requires engaging with its community to get the most of it -- OpenDev is not
a service you consume, it's a community you join. That can be a bit
overwhelming if you just want to focus on development, especially when
ready-to-consume services are available. But it's worth it, especially if you
want to have a say in what services are provided, or just support the idea of
improving open source tools in that space.</p>
<h2 id="faq">FAQ</h2>
@ -161,7 +170,7 @@ problems.</p>
<h3 id="why-cant-we-use-giteas-issue-tracker-and-wiki">Why can't we use Gitea's issue tracker and wiki?</h3>
<p>For scaling and redundancy purposes we are actually
running a number of independent Giteas behind a load balancer. We can keep
git repos in sync from Gerrit reasonably well, but the issue tracker and
Git repos in sync from Gerrit reasonably well, but the issue tracker and
wiki functionality would need another level of state syncing. Once Gitea
can be run as a proper cluster this may change, but until then the
functionality is limited.</p>