Document the development workflow of the fork #5
Labels
No labels
arch
amd64
arch
arm6
arch
arm64
arch
arm7
arch
riscv64
backport/v1.19
backport/v1.20
backport/v1.21/forgejo
backport/v7.0/forgejo
backport/v8.0/forgejo
breaking
bug
bug
confirmed
bug
duplicate
bug
needs-more-info
bug
new-report
bug
reported-upstream
codeberg
database
CockroachDB
database
MySQL
database
PostgreSQL
database
SQLite
dependency-upgrade
dependency
ACT
dependency
alpine
dependency
asciinema-player
dependency
bleve
dependency
cache
dependency
certmagic
dependency
chart.js
dependency
Chi
dependency
Chroma
dependency
citation.js
dependency
codespell
dependency
css-loader
dependency
devcontainers
dependency
dropzone
dependency
editorconfig-checker
dependency
elasticsearch
dependency
enmime
dependency
F3
dependency
ForgeFed
dependency
garage
dependency
Git
dependency
git-backporting
dependency
Gitea
dependency
gitignore
dependency
go-ap
dependency
go-enry
dependency
go-gitlab
dependency
Go-org
dependency
go-rpmutils
dependency
go-sql-driver mysql
dependency
go-swagger
dependency
go-version
dependency
go-webauthn
dependency
gocron
dependency
Golang
dependency
goldmark
dependency
goquery
dependency
Goth
dependency
grpc-go
dependency
happy-dom
dependency
Helm
dependency
image-spec
dependency
jsonschema
dependency
KaTeX
dependency
lint
dependency
MariaDB
dependency
Mermaid
dependency
minio-go
dependency
misspell
dependency
Monaco
dependency
PDFobject
dependency
playwright
dependency
postcss
dependency
postcss-plugins
dependency
pprof
dependency
prometheus client_golang
dependency
protobuf
dependency
relative-time-element
dependency
renovate
dependency
reply
dependency
ssh
dependency
swagger-ui
dependency
tailwind
dependency
temporal-polyfill
dependency
terminal-to-html
dependency
tests-only
dependency
text-expander-element
dependency
urfave
dependency
vfsgen
dependency
vite
dependency
Woodpecker CI
dependency
x tools
dependency
XORM
Discussion
duplicate
enhancement/feature
forgejo/accessibility
forgejo/actions
forgejo/api
forgejo/branding
forgejo/ci
forgejo/documentation
forgejo/email
forgejo/federation
forgejo/furnace cleanup
forgejo/internationalization
forgejo/moderation
forgejo/privacy
forgejo/release
forgejo/scaling
forgejo/security
forgejo/ui
Gain
High
Gain
Nice to have
Gain
Undefined
Gain
Very High
good first issue
issue
closed
issue
do-not-exist-yet
issue
open
manual test
Manually tested during feature freeze
OS
FreeBSD
OS
Linux
OS
MacOS
OS
Windows
regression
release blocker
Release Cycle
Feature Freeze
release-blocker
v7.0
release-blocker
v7.0.1
release-blocker
v7.0.2
release-blocker
v7.0.3
release-blocker
v7.0.4
release-blocker
v8.0.0
run-end-to-end-tests
test
manual
test
needed
test
needs-help
test
not-needed
test
present
untested
valuable code
worth a release-note
User Research - Accessibility
User Research - bug
User Research - Config (instance)
User Research - Dashboard
User Research - documentation
User Research - Errors
User Research - feature
User Research - federation
User Research - Filters
User Research - governance
User Research - Labels
User Research - Moderation
User Research - Needs Input
User Research - Notifications
User Research - release
User Research - Repo creation
User Research - Repo Units
User Research - security
User Research - Settings (in-app)
User Research - testing
User Research - UI
User Research - UX
No milestone
No project
No assignees
5 participants
Notifications
Due date
No due date set.
Blocks
#9 Replace the issue templates
forgejo/forgejo
Reference: forgejo/forgejo#5
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Draft documentation of the development workflow in the pad for collaborative editing https://pad.gusted.xyz/Rs70GWB6SWi27B44tBCpKA?view
The development workflow of a soft fork means maintaining a set of patches that are to be applied to the development and stable branches of Gitea over a long period of time because (for whatever reason) they are not going to be merged in Gitea.
This is a well established practice in the Free Software world:
It must be done a sane way, to keep the technical debt associated with it in check at all times.
Codeberg fork development workflow
The development workflow in place at https://codeberg.org/codeberg/gitea works fine for now but has a significant drawback. The content of the patch is split between the patch itself and the conflict resolution that happens when merging the upstream branch. Whatever workflow is decided must avoid that pitfall.
forgefriends fork development workflow
The development workflow in place at forgefriends https://forum.forgefriends.org/t/cheatlist-for-forgefriends-development/429 has worked well in the past year with weekly rebasing. It resembles what Linux kernel developpers do which essentially boils down to:
This issue was moved from codename/meta#22
For the record, a related discussion happened here codename/codename#7 (comment)
@codename/Owners My preferred development workflow for "codename" is to have feature branches where changes are maintained, rebased on Gitea main for development and rebased on Gitea stable branches for backports. It is similar to what kernel developers do when they do not work mainline and it is what was chosen for forgefriends.
The feature branches are merged together in an integration branch for testing. If the tests pass, the "codename" branch is reset hard to the tip of the integration branch. Releases are created by setting tags on the tip of the "codename" branch. Nothing is ever merged in the "codename" branch.
I'll document that in detail if there is a consensus to go in this direction.
I never used feature branches, but happy to experiment with it. LGTM.
@Gusted Do you need some general introduction material? (With charts and everything)
@dachary If we go with feature branches, will this be kind of
git flowor something different?Nah, not really. I can likely pick up the flow, but we might need those for those that are less experienced with Git/workflows.
Hi all,
watching here and thinking hard about what I'd prefer. The basic outcome is: Let's be flexible, see what works for us, and easily propose and communicate changes.
A first requirement everyone can accept, is that development branches are rebased and force-pushed. This might and will lead to confusion, e.g. if a newly opened PR targets the main branch, but we just rebased our state, and now the base for the PR is gone. We could also consider using a schedule, e.g. rebase three times a week on fixed dates, and otherwise merge if possible.
What we should always avoid is doing conflict resolution during merge, because this means that we will have to resolve a conflict twice or fiddle deeply with Git (and from my experience, not everyone is into this).
So far, my proposal works like this:
Would that work for you if CN/type were branches instead of commits? One branch per commit (and maybe group some of them in the same branch if that makes more sense). Working on one commit is more challenging than working on a branch. A branch allows for:
@dachary 's original proposal makes sense to me on a superficial reading, @fnetX 's proposal I find harder to follow. But I have no experience working with a soft fork like this where patches have to be kept up to date, so I'll let the two of you who do have that experience work it out!
I think very clear documentation will be vital if we want contributions from folks who aren't Git workflow experts. Eg, what branch should someone send PRs against? Etc. Ideally it should be as easy to contribute as just sending a PR to the
mainbranch of any other project. The more the complicated workflow can be "hidden" the better.I wonder if there's anything to learn from Electron, who effectively maintain a very complicated soft fork of Chromium...
@dachary we can try this with branches. I only now understand your proposal with all the implications. I think I'd find it more confusing to handle all the branches, because a simple "rebase" takes care of all the commits, and with branches it might be harder to remember in which order the commits were applied, or which commits to apply at all. But let's try.
I'll document the "feature branch" workflow then.
It is indeed less straightforward than to rebase a list of patches, that's one drawback, I won't pretend otherwise. But I believe that overall the "pros" outweigh the "cons".
I assume you will update
CONTRIBUTING.mdaccordingly, @dachary?Another consideration, how will we handle translations? (Perhaps that's for a separate issue…)
Yes.
That's a very difficult topic unfortunately. Realistically I don't see how to participate in the translations in any way as the process in place is bound to crowdin. But indeed, that's worth a different issue :-)
If we introduce new strings, we could add them using a prefix for now. Not optimal long-term, but works for now.
I'm actually planning to do this for Codeberg using a separate file and patching our build script to merge them, because all Codeberg-specific templates are currently untranslated.
We could then add such file(s) to the Codeberg Weblate Instance.
caesar referenced this issue2022-11-10 10:16:36 +00:00
Starting a pad to document the workflow https://pad.gusted.xyz/Rs70GWB6SWi27B44tBCpKA#
Here is a first draft. What do you think?
Codename is a soft fork, i.e. a set of commits applied to the Gitea development branch and the stable branches. On a regular basis those commits are rebased and modified if necessary to keep working. All Codename commits are merged into a branch from which binary releases and packages are created and distributed. The development workflow is a set of conventions Codename developers are expected to follow to work together.
Naming conventions
Development
Stable
Rebasing
The latest Gitea branch resets the Integration branch and all Feature branches are merged into it.
If tests pass, the Codename branch is reset to the tip of the Integration branch.
If tests do not pass, an issue is filed to the Feature branch that fails the test. Once the issue is resolved, another round of rebasing starts.
Releasing
When a tag is set to a Stable Codename branch, the CI pipeline creates and uploads binaries and packages.
Feature branches
All Feature branches are based on the *codename-development branch which provides the Woodpecker CI configuration and other development tools.
I think it could do with a simple overview of how a new contributor should work. It needs to answer at least the following questions:
For example, most people who are used to contributing to open-source code will be familiar with the workflow of sending a PR against the repo's default branch.
In the case of contributing to Codename, they need to know what's different compared to that familiar workflow.
Very good point, the draft was modified and now ends with:
Feature branches
All Feature branches are based on the *codename-development branch which provides the Woodpecker CI configuration and other development tools.
The purpose of each Feature branch is documented in CONTRIBUTING.md as follows:
Contributing
Most people who are used to contributing will be familiar with the workflow of sending a pull request against the default branch. When that happens the reviewer should change the base branch to the appropriate Feature branch instead. If the pull request does not fit in any Feature branch, the reviewer needs to make decision to either:
Returning contributors can figure out which Feature branch to base their pull request on using the list of Feature branches found in CONTRIBUTING.md
Node.js world has commitlint to validate this.
This could lead to a lock state.
What if multiple feature branches fail? When will the round start? As soon as the first one is resolved? Waiting for all of them?
It's worth starting a new round each time a feature branch is fixed, IMHO.
So just to clarify: an external contributor sending a PR for a new feature should send it against the default branch, and whoever reviews it will create a branch for it?
Yes, in the most complicated case where an external contributor:
A more likely scenario, IMHO, is when an external contributor:
The reviewer would then just ask the external contributor to change the base branch like below or do it themselves.
Does that sound reasonable?
Yes, that makes sense to me - I think the granularity of the "feature branches" is probably coarser than I had initially imagined, which will make it easier to keep them up to date.
The granularity of the branches is indeed of significant importance to keep the friction minimum and the features isolated. A single feature branch grouping all commits related to branding Codename would make sense to me and allow people to focus on that topic. If it is split into multiple branches, one dealing with s/Gitea/Codename/ and another dealing with the web UI, that may also make sense but probably require more coordination and increase the chances of conflicts when merging. Creating a new branch for each commit is likely to be too fine grain, very cumbersome and confusing.
I don't think it is possible to write down a policy that explains how to keep that balance, it's a mix of common sense and dialog among developers. I also think that once there are a few branches in place and a few weekly merge happened, it will become clearer.
If this discussion settles down for a bit and a consensus emerges I would be happy to create a decision diagram using mermaid and PR the CONTRIBUTION.md file.
I added a section about the granularity of branches to the workflow documentation
https://pad.gusted.xyz/Rs70GWB6SWi27B44tBCpKA?view#Granularity
it probably is going to come up a few times.
Updated the pad https://pad.gusted.xyz/Rs70GWB6SWi27B44tBCpKA to reword the part about rebasing. While explaining it during the forgefriends coworking session (recording will be available today), I realized it was missing a bit of information.
dachary referenced this issue2022-11-15 17:07:23 +00:00
It is now in https://codeberg.org/codename/codename/src/branch/codename/WORKFLOW.md
I opened codename/codename#12 to discuss the details of bootstraping the development workflow. It's far from perfect but we can improve on it.