fix

README.md

@@ -14,21 +14,21 @@
 
 ## Purpose
 
-The goal of this project is to make the easiest, fastest, and most
+The goal of Gitea is to make the easiest, fastest, and most painless way of
-painless way of setting up a self-hosted Git service.
+setting up a self-hosted all-in-one software development service,
+including Git hosting, code management, code review, issue tracking, project kanban, wiki,
+team collaboration, package registry and CI/CD which can reuse GitHub Actions.
 
 As Gitea is written in Go, it works across **all** the platforms and
 architectures that are supported by Go, including Linux, macOS, and
 Windows on x86, amd64, ARM and PowerPC architectures.
-This project has been
-[forked](https://blog.gitea.com/welcome-to-gitea/) from
-[Gogs](https://gogs.io) since November of 2016, but a lot has changed.
 
 For online demonstrations, you can visit [demo.gitea.com](https://demo.gitea.com).
 
 For accessing free Gitea service (with a limited number of repositories), you can visit [gitea.com](https://gitea.com/user/login).
 
-To quickly deploy your own dedicated Gitea instance on Gitea Cloud, you can start a free trial at [cloud.gitea.com](https://cloud.gitea.com).
+To quickly deploy your own dedicated Gitea instance on Gitea Cloud, you can start a free trial at [cloud.gitea.com](https://cloud.gitea.com),
+or use container (docker/podman/etc) to deploy on your own server with the [official image](https://hub.docker.com/r/gitea/gitea).
 
 ## Documentation
 
@@ -40,23 +40,12 @@ If you have any suggestions or would like to contribute to it, you can visit the
 
 ## Building
 
-From the root of the source tree, run:
+See [docs/build-setup.md](docs/build-setup.md) for prerequisites
+and [docs/development.md](docs/development.md) for setting up a local development environment, linting, and testing.
 
-    TAGS="bindata" make build
+If you'd like to build from source or make a distribution package, see [docs/build-source.md](docs/build-source.md) for more information.
 
-See [docs/setup.md](docs/setup.md) for prerequisites and [docs/development.md](docs/development.md)
+After building, you can run `./gitea web` to start the server, or `./gitea help` to see all available commands.
-for setting up a local development environment, continuous builds, linting, and testing.
-
-More info: https://docs.gitea.com/installation/install-from-source
-
-## Using
-
-After building, a binary file named `gitea` will be generated in the root of the source tree by default. To run it, use:
-
-    ./gitea web
-
-> [!NOTE]
-> If you're interested in using our APIs, we have experimental support with [documentation](https://docs.gitea.com/api).
 
 ## Contributing
 
@@ -123,14 +112,19 @@ Support this project by becoming a sponsor. Your logo will show up here with a l
 
 Gitea is pronounced [/ɡɪ’ti:/](https://youtu.be/EM71-2uDAoY) as in "gi-tea" with a hard g.
 
-**Why is this not hosted on a Gitea instance?**
+**How do I configure Gitea?**
 
-We're [working on it](https://github.com/go-gitea/gitea/issues/1029).
+For dynamic config options, you can change it on your admin panel's configuration section.
+
+For static config options, you can edit your `app.ini` file and resart the instance.
+See [app.example.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini) or [configuration documentation](https://docs.gitea.com/administration/config-cheat-sheet) for more details.
 
 **Where can I find the security patches?**
 
 In the [release log](https://github.com/go-gitea/gitea/releases) or the [change log](https://github.com/go-gitea/gitea/blob/main/CHANGELOG.md), search for the keyword `SECURITY` to find the security patches.
 
+(more FAQs are listed in [FAQ documentation](https://docs.gitea.com/help/faq))
+
 ## License
 
 This project is licensed under the MIT License.
@@ -140,7 +134,7 @@ for the full license text.
 ## Further information
 
 <details>
-<summary>Looking for an overview of the interface? Check it out!</summary>
+<summary>Looking for an overview of the interface? Check it out the screenshots!</summary>
 
 ### Login/Register Page
 

docs/build-source.md

@@ -0,0 +1,94 @@
+# Prepare build environment
+
+Complete the steps in [build-setup.md](build-setup.md) to prepare your environment for building Gitea from source.
+
+## Choose a branch
+
+By default, the cloned repository is on main branch (the current development branch for next major release, aka: main nightly).
+
+You can switch to a versioned branch (the branch for the next minor stable release, aka: stable nightly )
+or a versioned tag (matches the official releases with version numbers)
+
+To test a Pull Request, you can fetch its code by its Pull Request number (take `PR #123456` as example):
+
+```bash
+git fetch origin pull/123456/head:pr-123456
+```
+
+# Build
+
+Various [make tasks](https://github.com/go-gitea/gitea/blob/main/Makefile)
+are provided to keep the build process as simple as possible.
+
+Depending on requirements, the following build tags can be included.
+
+- `bindata`: Build a single monolithic binary, with all assets included. Required for distribution and production build.
+- `pam`: Enable support for PAM (Linux Pluggable Authentication Modules).
+  Can be used to authenticate local users or extend authentication to methods available to PAM.
+- `gogit`: (EXPERIMENTAL) Use go-git variants of Git commands.
+
+To include all assets, use the `bindata` tag:
+
+```bash
+TAGS="bindata" make build
+```
+
+`gogit` is used to try to resolve some Windows-specific performance problems, you can build a Windows binary by:
+
+```bash
+GOOS=windows TAGS="bindata gogit" make build
+```
+
+## Changing default paths
+
+Gitea will search for a number of things from the _`CustomPath`_.
+By default, this is the `custom/` directory in the current working directory when running Gitea.
+It will also look for its configuration file _`CustomConf`_ in `$(CustomPath)/conf/app.ini`,
+and will use the current working directory as the relative base path _`AppWorkPath`_.
+The static files will be served from _`StaticRootPath`_ which defaults to the _`AppWorkPath`_.
+
+These values, although useful when developing, may conflict with downstream users preferences.
+
+For packagers who need to use paths like `/etc/gitea/app.ini`,
+they should define these values at build time by `LDFLAGS` environment variable for `make`.
+The appropriate settings are as follows:
+
+- To set the _`CustomPath`_ use `LDFLAGS="-X \"code.gitea.io/gitea/modules/setting.CustomPath=custom-path\""`
+- For _`CustomConf`_ you should use `-X \"code.gitea.io/gitea/modules/setting.CustomConf=conf.ini\"`
+- For _`AppWorkPath`_ you should use `-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"`
+- For _`StaticRootPath`_ you should use `-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"`
+- To change the default PID file location use `-X \"code.gitea.io/gitea/cmd.PIDFile=/run/gitea.pid\"`
+
+Add as many of the strings with their preceding `-X` to the `LDFLAGS` variable and run `make build`
+with the appropriate `TAGS` as above.
+
+Running `gitea help` will allow you to review what the computed settings will be for your `gitea`.
+
+## Cross Build
+
+Gitea use's Golang's toolchain variables for cross-building.
+
+For example, to cross build for Linux ARM64:
+
+```
+GOOS=linux GOARCH=arm64 TAGS="bindata" make build
+```
+
+### Adding shell autocompletion
+
+Shell completion can be generated directly from binary with:
+
+```sh
+gitea completion <shell>
+```
+
+Supported values for `<shell>` are `bash`, `fish`, `pwsh` and `zsh`.
+Details on how to load the completion for your shell can be found in the completion command help.
+
+## Source Maps
+
+By default, gitea generates reduced source maps for frontend files to conserve space. This can be controlled with the `ENABLE_SOURCEMAP` environment variable:
+
+- `ENABLE_SOURCEMAP=true` generates all source maps, the default for development builds
+- `ENABLE_SOURCEMAP=reduced` generates limited source maps, the default for production builds
+- `ENABLE_SOURCEMAP=false` generates no source maps