From e3317cd8698e9b3b2a095ba12a39fc2d6631f519 Mon Sep 17 00:00:00 2001 From: Nicolas Date: Thu, 9 Jul 2026 23:55:17 +0000 Subject: [PATCH] Move Hacking to Gitea main repo (#429) Related: https://github.com/go-gitea/gitea/pull/37960 Co-authored-by: Lunny Xiao Co-authored-by: wxiaoguang <29147+wxiaoguang@noreply.gitea.com> Reviewed-on: https://gitea.com/gitea/docs/pulls/429 Reviewed-by: Lunny Xiao Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com> Co-authored-by: Nicolas --- docs/contributing/_category_.json | 9 - docs/contributing/contributing.md | 76 ---- docs/contributing/guidelines-backend.md | 115 ------ docs/contributing/guidelines-frontend.md | 156 -------- docs/contributing/guidelines-refactoring.md | 40 -- docs/contributing/localization.md | 30 -- docs/development/hacking-on-gitea.md | 372 ------------------ docs/installation/from-source.md | 2 + sidebars.js | 14 - .../version-1.27/contributing/_category_.json | 9 - .../version-1.27/contributing/contributing.md | 76 ---- .../contributing/guidelines-backend.md | 115 ------ .../contributing/guidelines-frontend.md | 156 -------- .../contributing/guidelines-refactoring.md | 40 -- .../version-1.27/contributing/localization.md | 30 -- .../development/hacking-on-gitea.md | 372 ------------------ .../version-1.27/installation/from-source.md | 2 + versioned_sidebars/version-1.27-sidebars.json | 13 - 18 files changed, 4 insertions(+), 1623 deletions(-) delete mode 100644 docs/contributing/_category_.json delete mode 100644 docs/contributing/contributing.md delete mode 100644 docs/contributing/guidelines-backend.md delete mode 100644 docs/contributing/guidelines-frontend.md delete mode 100644 docs/contributing/guidelines-refactoring.md delete mode 100644 docs/contributing/localization.md delete mode 100644 docs/development/hacking-on-gitea.md delete mode 100644 versioned_docs/version-1.27/contributing/_category_.json delete mode 100644 versioned_docs/version-1.27/contributing/contributing.md delete mode 100644 versioned_docs/version-1.27/contributing/guidelines-backend.md delete mode 100644 versioned_docs/version-1.27/contributing/guidelines-frontend.md delete mode 100644 versioned_docs/version-1.27/contributing/guidelines-refactoring.md delete mode 100644 versioned_docs/version-1.27/contributing/localization.md delete mode 100644 versioned_docs/version-1.27/development/hacking-on-gitea.md diff --git a/docs/contributing/_category_.json b/docs/contributing/_category_.json deleted file mode 100644 index bdd6dff8..00000000 --- a/docs/contributing/_category_.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "label": "Contributing", - "position": 35, - "link": { - "type": "generated-index", - "slug": "/contributing", - "title": "Contributing" - } -} diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md deleted file mode 100644 index 98ca500c..00000000 --- a/docs/contributing/contributing.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -slug: "contributing" -sidebar_position: 1 ---- - -# Contributing to Gitea - -Thank you for your interest in contributing to Gitea! This guide will help you understand how to contribute to the project effectively. - -## Getting Started - -Before you start contributing, please read our [Hacking on Gitea](../development/hacking-on-gitea) guide to set up your development environment. - -## Contribution Guidelines - -We have specific guidelines for different types of contributions: - -### Backend Development - -If you're working on backend code (Go), please follow our [Guidelines for Backend Development](./guidelines-backend). This includes: - -- Package design and dependencies -- Database operations and migrations -- Testing strategies -- Code organization - -### Frontend Development - -For frontend contributions (JavaScript, CSS, Vue), refer to our [Guidelines for Frontend Development](./guidelines-frontend). This covers: - -- Framework usage (Vue3, Fomantic-UI) -- Code style and best practices -- Accessibility requirements -- TypeScript usage - -### Refactoring - -When refactoring existing code, follow our [Guidelines for Refactoring](./guidelines-refactoring) to ensure: - -- Clear refactoring objectives -- Proper review process -- Maintaining backward compatibility -- Incremental improvements - -### Localization - -To contribute translations or localization improvements, see our [Localization Guide](./localization) which explains: - -- How to contribute translations via Crowdin -- Supported languages -- Translation workflow - -## Code of Conduct - -Please be respectful and constructive in all interactions with the community. We are committed to providing a welcoming and inclusive environment for all contributors. - -## Getting Help - -If you need help with your contribution: - -- Join our [Discord](https://discord.gg/gitea) #Develop channel -- Visit our [Forum](https://forum.gitea.com/) -- Check existing [GitHub Issues](https://github.com/go-gitea/gitea/issues) - -## Submitting Your Contribution - -1. Fork the repository -2. Create a feature branch -3. Make your changes following the relevant guidelines -4. Write tests for your changes -5. Ensure all tests pass -6. Submit a pull request - -For more details, see our [CONTRIBUTING.md](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md) in the main repository. - -Thank you for helping make Gitea better! diff --git a/docs/contributing/guidelines-backend.md b/docs/contributing/guidelines-backend.md deleted file mode 100644 index 8748a0f0..00000000 --- a/docs/contributing/guidelines-backend.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -date: "2021-11-01T23:41:00+08:00" -slug: "guidelines-backend" -sidebar_position: 20 -aliases: - - /en-us/guidelines-backend ---- - -# Guidelines for Backend Development - -## Background - -Gitea uses Golang as the backend programming language. It uses many third-party packages and also write some itself. -For example, Gitea uses [Chi](https://github.com/go-chi/chi) as basic web framework. [Xorm](https://xorm.io) is an ORM framework that is used to interact with the database. -So it's very important to manage these packages. Please take the below guidelines before you start to write backend code. - -## Package Design Guideline - -### Packages List - -To maintain understandable code and avoid circular dependencies it is important to have a good code structure. The Gitea backend is divided into the following parts: - -- `build`: Scripts to help build Gitea. -- `cmd`: All Gitea actual sub commands includes web, doctor, serv, hooks, admin and etc. `web` will start the web service. `serv` and `hooks` will be invoked by Git or OpenSSH. Other sub commands could help to maintain Gitea. -- `tests`: Common test utility functions - - `tests/integration`: Integration tests, to test back-end regressions - - `tests/e2e`: E2e tests, to test front-end and back-end compatibility and visual regressions. -- `models`: Contains the data structures used by xorm to construct database tables. It also contains functions to query and update the database. Dependencies to other Gitea code should be avoided. You can make exceptions in cases such as logging. - - `models/db`: Basic database operations. All other `models/xxx` packages should depend on this package. The `GetEngine` function should only be invoked from `models/`. - - `models/fixtures`: Sample data used in unit tests and integration tests. One `yml` file means one table which will be loaded into database when beginning the tests. - - `models/migrations`: Stores database migrations between versions. PRs that change a database structure **MUST** also have a migration step. -- `modules`: Different modules to handle specific functionality in Gitea. Work in Progress: Some of them should be moved to `services`, in particular those that depend on models because they rely on the database. - - `modules/setting`: Store all system configurations read from ini files and has been referenced by everywhere. But they should be used as function parameters when possible. - - `modules/git`: Package to interactive with `Git` command line or Gogit package. -- `public`: Compiled frontend files (javascript, images, css, etc.) -- `routers`: Handling of server requests. As it uses other Gitea packages to serve the request, other packages (models, modules or services) must not depend on routers. - - `routers/api` Contains routers for `/api/v1` aims to handle RESTful API requests. - - `routers/install` Could only respond when system is in INSTALL mode (INSTALL_LOCK=false). - - `routers/private` will only be invoked by internal sub commands, especially `serv` and `hooks`. - - `routers/web` will handle HTTP requests from web browsers or Git SMART HTTP protocols. -- `services`: Support functions for common routing operations or command executions. Uses `models` and `modules` to handle the requests. -- `templates`: Golang templates for generating the html output. - -### Package Dependencies - -Since Golang doesn't support import cycles, we have to decide the package dependencies carefully. There are some levels between those packages. Below is the ideal package dependencies direction. - -`cmd` -> `routers` -> `services` -> `models` -> `modules` - -From left to right, left packages could depend on right packages, but right packages MUST not depend on left packages. The sub packages on the same level could depend on according this level's rules. - -:::warning -Why do we need database transactions outside of `models`? And how? -Some actions should allow for rollback when database record insertion/update/deletion failed. -So services must be allowed to create a database transaction. Here is some example, - -```go -// services/repository/repository.go -func CreateXXXX() error { - return db.WithTx(func(ctx context.Context) error { - // do something, if err is returned, it will rollback automatically - if err := issues.UpdateIssue(ctx, repoID); err != nil { - // ... - return err - } - // ... - return nil - }) -} -``` - -You should **not** use `db.GetEngine(ctx)` in `services` directly, but just write a function under `models/`. -If the function will be used in the transaction, just let `context.Context` as the function's first parameter. - -```go -// models/issues/issue.go -func UpdateIssue(ctx context.Context, repoID int64) error { - e := db.GetEngine(ctx) - - // ... -} -``` -::: - -### Package Name - -For the top level package, use a plural as package name, i.e. `services`, `models`, for sub packages, use singular, -i.e. `services/user`, `models/repository`. - -### Import Alias - -Since there are some packages which use the same package name, it is possible that you find packages like `modules/user`, `models/user`, and `services/user`. When these packages are imported in one Go file, it's difficult to know which package we are using and if it's a variable name or an import name. So, we always recommend to use import aliases. To differ from package variables which are commonly in camelCase, just use **snake_case** for import aliases. -i.e. `import user_service "code.gitea.io/gitea/services/user"` - -### Implementing `io.Closer` - -If a type implements `io.Closer`, calling `Close` multiple times must not fail or `panic` but return an error or `nil`. - -### Important Gotchas - -- Never write `x.Update(exemplar)` without an explicit `WHERE` clause: - - This will cause all rows in the table to be updated with the non-zero values of the exemplar - including IDs. - - You should usually write `x.ID(id).Update(exemplar)`. -- If during a migration you are inserting into a table using `x.Insert(exemplar)` where the ID is preset: - - You will need to ``SET IDENTITY_INSERT `table` ON`` for the MSSQL variant (the migration will fail otherwise) - - However, you will also need to update the id sequence for postgres - the migration will silently pass here but later insertions will fail: - ``SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false)`` - -### Future Tasks - -Currently, we are creating some refactors to do the following things: - -- Correct that codes which doesn't follow the rules. -- There are too many files in `models`, so we are moving some of them into a sub package `models/xxx`. -- Some `modules` sub packages should be moved to `services` because they depend on `models`. diff --git a/docs/contributing/guidelines-frontend.md b/docs/contributing/guidelines-frontend.md deleted file mode 100644 index 7a1312e5..00000000 --- a/docs/contributing/guidelines-frontend.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -date: "2021-10-13T16:00:00+02:00" -slug: "guidelines-frontend" -sidebar_position: 30 -aliases: - - /en-us/guidelines-frontend ---- - -# Guidelines for Frontend Development - -## Background - -Gitea uses [Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html) (based on [jQuery](https://api.jquery.com)) and [Vue3](https://vuejs.org/) for its frontend. - -The HTML pages are rendered by [Go HTML Template](https://pkg.go.dev/html/template). - -The source files can be found in the following directories: - -* **CSS styles:** `web_src/css/` -* **JavaScript files:** `web_src/js/` -* **Vue components:** `web_src/js/components/` -* **Go HTML templates:** `templates/` - -## General Guidelines - -We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html) and [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) - -### Gitea specific guidelines - -1. Every feature (Fomantic-UI/jQuery module) should be put in separate files/directories. -2. HTML ids and classes should use kebab-case, it's preferred to contain 2-3 feature related keywords. -3. HTML ids and classes used in JavaScript should be unique for the whole project, and should contain 2-3 feature related keywords. We recommend to use the `js-` prefix for classes that are only used in JavaScript. -4. CSS styling for classes provided by frameworks should not be overwritten. Always use new class names with 2-3 feature related keywords to overwrite framework styles. Gitea's helper CSS classes in `helpers.less` could be helpful. -5. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`, but do not expose whole models to the frontend to avoid leaking sensitive data. -6. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue3. -7. Clarify variable types, prefer `elem.disabled = true` instead of `elem.setAttribute('disabled', 'anything')`, prefer `$el.prop('checked', var === 'yes')` instead of `$el.prop('checked', var)`. -8. Use semantic elements, prefer `