forgejo/docs
31
58
Fork
You've already forked docs
249

developer: add ARCHITECTURE file #81

Merged
caesar merged 1 commit from architecture into next 2023年08月30日 23:19:34 +02:00

Please feel free to suggest sections that should be included in this document or certain concepts that should be mentioned. I'm probably not the best person to put this together as I have flawed view of the architecture and likely have missed certain points that should be pointed out (especially in the Bird's-eye view section).

- As per https://codeberg.org/forgejo/discussions/issues/53#issuecomment-1070207 Please feel free to suggest sections that should be included in this document or certain concepts that should be mentioned. I'm probably not the best person to put this together as I have flawed view of the architecture and likely have missed certain points that should be pointed out (especially in the Bird's-eye view section).
Collaborator
Copy link

Preview ready: https://forgejo.codeberg.page/@docs_pull_81/
https://forgejo.codeberg.page/@docs_pull_81/docs/v1.21/developer/architecture/
https://forgejo.codeberg.page/@docs_pull_81/docs/next/developer/architecture/

Preview ready: https://forgejo.codeberg.page/@docs_pull_81/ https://forgejo.codeberg.page/@docs_pull_81/docs/v1.21/developer/architecture/ https://forgejo.codeberg.page/@docs_pull_81/docs/next/developer/architecture/
@ -0,0 +10,4 @@
## Bird's-eye view
Forgejo serves as a git server and frontend; users can pull and push to git repositories and view commits and their diff, Forgejo handles the authentication and executes actions based on the context of the request, such as sending a notification if the pushed commit was part of a pull request or getting a diff and syntax-highlighting that between two commits if the compare page is requested. Forgejo doesn’t touch the git repository itself; it leaves that to the `git` binary.
Contributor
Copy link

s/and syntax-highlighting that /(and syntax-highlighting that)/ ? It reads funny otherwise.

s/and syntax-highlighting that /(and syntax-highlighting that)/ ? It reads funny otherwise.
Gusted marked this conversation as resolved
@ -0,0 +12,4 @@
Forgejo serves as a git server and frontend; users can pull and push to git repositories and view commits and their diff, Forgejo handles the authentication and executes actions based on the context of the request, such as sending a notification if the pushed commit was part of a pull request or getting a diff and syntax-highlighting that between two commits if the compare page is requested. Forgejo doesn’t touch the git repository itself; it leaves that to the `git` binary.
Forgejo provides a software development environment that is independent of the code associated with operating as a git server. The application handles logic and stores information in databases. The environment includes features such as user profiles, issue reporting, and packages.
Contributor
Copy link

Forgejo provides a software development environment that is independent of the code associated with operating as a git server

I'm not sure what you mean by that?

> Forgejo provides a software development environment that is independent of the code associated with operating as a git server I'm not sure what you mean by that?
Gusted marked this conversation as resolved
@ -0,0 +41,4 @@
### `routers/`
All code related to handling web and API routes resides in this directory.
Contributor
Copy link

s/handling web and API routes/handling network endpoints (Forgejo REST API, undocumented web API, Forgejo Actions internal API etc.)/?

s/handling web and API routes/handling network endpoints (Forgejo REST API, undocumented web API, Forgejo Actions internal API etc.)/?
Gusted marked this conversation as resolved
@ -0,0 +55,4 @@
This directory contains integration testing code.
The files prefixed with `api_` contain integration tests for API routes, while those without are integration tests for web routes.
Contributor
Copy link

Note: there are integration tests that do not use web routes such as integration/dump_restore_test.go or tests/integration/cmd_keys_test.go but the overwhelming majority are indeed about web routes. Somehow I failed to notice that. Interesting.

**Note:** there are integration tests that do not use web routes such as `integration/dump_restore_test.go` or `tests/integration/cmd_keys_test.go` but the overwhelming majority are indeed about web routes. Somehow I failed to notice that. Interesting.
Gusted marked this conversation as resolved
earl-warren left a comment
Copy link

Minor non blocking remarks. It is a good and useful overview 👍

Minor non blocking remarks. It is a good and useful overview 👍
Gusted force-pushed architecture from 6eb25d1e53
All checks were successful
pr / preview (pull_request) Successful in 40s
to a0f8480bca
All checks were successful
pr / preview (pull_request) Successful in 41s
2023年08月27日 12:34:02 +02:00 Compare
caesar left a comment
Copy link

This is really useful @Gusted. I've suggested a few changes below but overall it's great.

One other thing is that there are several other directories that aren't included here. Most of them are less important things but perhaps a list with a very brief description for each one (just a few words) would be useful?

This is really useful @Gusted. I've suggested a few changes below but overall it's great. One other thing is that there are several other directories that aren't included here. Most of them are less important things but perhaps a list with a very brief description for each one (just a few words) would be useful?
@ -0,0 +9,4 @@
## Bird's-eye view
Forgejo serves as a git server and frontend; users can pull and push to git repositories and view commits and their diff, Forgejo handles the authentication and executes actions based on the context of the request, such as sending a notification if the pushed commit was part of a pull request or getting a diff (and syntax-highlighting that) between two commits if the compare page is requested. Forgejo doesn’t touch the git repository itself; it leaves that to the `git` binary.
Member
Copy link

I guess "Git" should have a capital G (except when it's the name of the binary of course)

I guess "Git" should have a capital G (except when it's the name of the binary of course)
Owner
Copy link

Use it instead of that when referring to the diff syntax-highlighting

Use `it` instead of `that` when referring to the diff syntax-highlighting
Gusted marked this conversation as resolved
@ -0,0 +35,4 @@
### `web_src/`
All code related to the web frontend resides in this directory.
Member
Copy link

I think this is a little misleading since the templates are in a different directory, as are the route handlers, both of which could be considered to be "related to the web frontend".

Perhaps clearer phrasing might be as follows?

Frontend code for the web UI resides in this directory.

On the surface it's a small difference in phrasing but I think it's less misleading. Or maybe there's a clearer way to say it; I'm half asleep now and struggling to think of the best phraseology.

I think this is a little misleading since the templates are in a different directory, as are the route handlers, both of which could be considered to be "related to the web frontend". Perhaps clearer phrasing might be as follows? ``` Frontend code for the web UI resides in this directory. ``` On the surface it's a small difference in phrasing but I think it's less misleading. Or maybe there's a clearer way to say it; I'm half asleep now and struggling to think of the best phraseology.
Owner
Copy link

Hmm... That might still be too vague. Perhaps something like the following would be clear enough?

The sources used to generate static assets used by the web UI (such as JavaScript, CSS, and SVGs) are stored in this directory

EDIT: The following line does clarify about the JS and CSS stuff, so that can be omitted, I think the rest is still relevant.

Hmm... That might still be too vague. Perhaps something like the following would be clear enough? ``` The sources used to generate static assets used by the web UI (such as JavaScript, CSS, and SVGs) are stored in this directory ``` EDIT: The following line does clarify about the JS and CSS stuff, so that can be omitted, I think the rest is still relevant.
Member
Copy link

Yes, I think that's better.

Yes, I think that's better.
Gusted marked this conversation as resolved
@ -0,0 +47,4 @@
### `templates/`
The name is self-explanatory; this directory contains the HTML templates for the frontend.
Member
Copy link

I would personally remove The name is self-explanatory as I feel it adds nothing.

I would personally remove `The name is self-explanatory` as I feel it adds nothing.
Gusted marked this conversation as resolved
Ghost approved these changes 2023年08月28日 09:44:20 +02:00
@ -0,0 +11,4 @@
Forgejo serves as a git server and frontend; users can pull and push to git repositories and view commits and their diff, Forgejo handles the authentication and executes actions based on the context of the request, such as sending a notification if the pushed commit was part of a pull request or getting a diff (and syntax-highlighting that) between two commits if the compare page is requested. Forgejo doesn’t touch the git repository itself; it leaves that to the `git` binary.
Forgejo provides a software development environment that does not rely on or interact with Git for the most part, which means that the applications handles the logic and stores information in databases. The environment includes features such as user profiles, issue reporting, and packages.
Owner
Copy link

Add "also" after "Forgejo" to clarify the relation to the previous point

Is "the applications" referring to Forgejo? An s needs to be removed from "applications" or "handles" and "stores"

Add "also" after "Forgejo" to clarify the relation to the previous point Is "the applications" referring to Forgejo? An s needs to be removed from "applications" or "handles" and "stores"
Gusted marked this conversation as resolved
@ -0,0 +41,4 @@
### `routers/`
All code related to handling network endpoints (Forgejo REST API, web API, Forgejo Actions internal API etc.) resides in this directory.
Owner
Copy link

"web API" is kind of ambiguous

"web API" is kind of ambiguous
Gusted marked this conversation as resolved
@ -0,0 +63,4 @@
Unit tests are implemented in `<filename>_test.go_` for the corresponding `<filename>.go` code. Not all files will have unit tests.
They tests the expected result and behavior of the function.
Owner
Copy link

Replace tests with test or verify

Replace `tests` with `test` or `verify`
Gusted marked this conversation as resolved
Gusted force-pushed architecture from a0f8480bca
All checks were successful
pr / preview (pull_request) Successful in 41s
to ade3bff6ff
All checks were successful
pr / preview (pull_request) Successful in 37s
2023年08月30日 19:10:28 +02:00 Compare
Gusted force-pushed architecture from ade3bff6ff
All checks were successful
pr / preview (pull_request) Successful in 37s
to 693f849196
All checks were successful
pr / preview (pull_request) Successful in 39s
push / publish (push) Successful in 8s
backport / backport (pull_request) Successful in 5s
2023年08月30日 19:11:08 +02:00 Compare
crystal left a comment
Copy link

This should provide a good overview of how the codebase is organized for new contributors. Thanks, @Gusted!

This should provide a good overview of how the codebase is organized for new contributors. Thanks, @Gusted!
Gusted changed title from (削除) WIP: developer: add ARCHITECTURE file (削除ここまで) to developer: add ARCHITECTURE file 2023年08月30日 21:17:45 +02:00
caesar deleted branch architecture 2023年08月30日 23:19:34 +02:00
Sign in to join this conversation.
Labels
Clear labels
404
Broken links or missing content
backport/v1.19
Changes which should be backported to the v1.19 docs

Archived

backport/v1.20
Changes which should be backported to the v1.20 docs

Archived

backport/v1.21
Changes which should be backported to the v1.21 docs

Archived

backport/v10.0
Automated backport to v10.0

Archived

backport/v11.0
Automated backport to v11.0
backport/v12.0
Automated backport to v12.0

Archived

backport/v13.0
Automated backport to v13.0

Archived

backport/v14.0
Automated backport to v14.0

Archived

backport/v15.0
Automated backport to v15.0
backport/v16.0
Automated backport to v16.0
backport/v7.0
Automated backport to the v7.0 docs

Archived

backport/v8.0
Automated backport to the v8.0 docs

Archived

backport/v9.0
Automated backport to the v9.0 docs

Archived

good first issue
This issue is suitable for "drive-by contributors" wanting to contribute for the first time, and fixing it should be straightforward.
meta
Tooling and processes for maintaining the docs
new docs
Content to be added to the documentation

Archived

User research - Accessibility
Requires input about accessibility features, likely involves user testing.
User research - Blocked
Do not pick as-is! We are happy if you can help, but please coordinate with ongoing redesign in this area.
User research - Community
Community features, such as discovering other people's work or otherwise feeling welcome on a Forgejo instance.
User research - Config (instance)
Instance-wide configuration, authentication and other admin-only needs.
User research - Errors
How to deal with errors in the application and write helpful error messages.
User research - Filters
How filter and search is being worked with.
User research - Future backlog
The issue might be inspiring for future design work.
User research - Git workflow
AGit, fork-based and new Git workflow, PR creation etc
User research - Labels
Active research about Labels
User research - Moderation
Moderation Featuers for Admins are undergoing active User Research
User research - Needs input
Use this label to let the User Research team know their input is requested.
User research - Notifications/Dashboard
Research on how users should know what to do next.
User research - Rendering
Text rendering, markup languages etc
User research - Repo creation
Active research about the New Repo dialog.
User research - Repo units
The repo sections, disabling them and the "Add more" button.
User research - Security
User research - Settings (in-app)
How to structure in-app settings in the future?
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
6 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
forgejo/docs!81
Reference in a new issue
forgejo/docs
No description provided.
Delete branch "architecture"

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?