diff --git a/docker/gitea/custom/templates/home.tmpl b/docker/gitea/custom/templates/home.tmpl index b26ff824ab..714937da6c 100644 --- a/docker/gitea/custom/templates/home.tmpl +++ b/docker/gitea/custom/templates/home.tmpl @@ -26,101 +26,110 @@
-

What is Opendev?

-

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.

+

What is OpenDev?

+

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.

-

How is development different with Opendev

-

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.

-

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.

-

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.

+

How is development different with OpenDev

+

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.

+

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.

+

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.

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.

+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.

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.

-

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.

+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.

+

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.

Integrated Continuous Integration

-

One key benefit of Opendev is that it integrates +

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.

+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.

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.

+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.

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.

+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.

Free software needs free tools

-

Finally, another key difference between Opendev and +

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?

-

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.

-

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.

+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)?

+

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.

+

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.

FAQ

@@ -161,7 +170,7 @@ problems.

Why can't we use Gitea's issue tracker and wiki?

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.