Re: [PATCH gitk] gitk: add README.md with contribution guidelines
Thank you. However, I hate to say that this isn't the text that I would expect on the front page of the repository.
An important part is missing: first-time visitors are not addressed at all. We should state what this software is about and show examples how to use it effectively, perhaps include a link to the manual (https://git-scm.com/docs/gitk).
I would prefer not to have format-patch+send-email tutorial in this text nor how to make Github PRs. It is OK to have links to tutorials. The prefix [PATCH gitk] hasn't been used in the past, but we do have the convention that commit summaries have the prefix 'gitk:'. This alone distinguishes submissions sufficiently (and then also simplifies using 'git format-patch' a bit).
Do not say that "this is the official repository". Remember that every clone would say that, too. That would be confusing. In the Git world, this status isn't achieved by proclamation, but by convention.
I wouldn't include the details how Gitk is also shipped with the Git repository, but at most that it is. It is not even necessary to discourage people from making patches in the gitk-git/ directory. `git am -3` can cope with such patches quite well. Allowing such contributions lowers the entry barrier.
Am 20.08.25 um 21:52 schrieb Michael Rappazzo:
Show 76 quoted lines
> Signed-off-by: Michael Rappazzo <rappazzo@gmail.com>
> ---
> README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 63 insertions(+)
> create mode 100644 README.md
>
> diff --git a/README.md b/README.md
> new file mode 100644
> index 0000000000..adf7a0ba85
> --- /dev/null
> +++ b/README.md
> @@ -0,0 +1,63 @@
> +# gitk - The Git Repository Browser
> +
> +This is the official repository for gitk, a graphical Git repository browser.
> +
> +## Repository Status
> +
> +- **Official Repository**: https://github.com/j6t/gitk
> +- **Integration**: This repository is regularly merged into the main Git repository (git.git) via subtree merges into the `gitk-git/` subdirectory
> +
> +## Contributing
> +
> +Contributions are welcome! The preferred method for submitting patches is via email to the Git mailing list, as this allows for more thorough review and broader community feedback. However, GitHub pull requests are also accepted.
> +
> +All commits must be signed off (use `git commit --signoff`).
> +
> +### Email Patches
> +- Create patches from this repository (github.com/j6t/gitk), not from the `gitk-git/` subdirectory in git.git
> +- Send patches to the Git mailing list: git@vger.kernel.org and CC the maintainer: j6t@kdbg.org
> +- Follow the Git project's patch submission guidelines
> +- Include `[PATCH gitk]` in the subject line
> +
> +#### Creating and Sending Patches
> +After committing your changes:
> +```bash
> +git format-patch -1 --subject-prefix="PATCH gitk"
> +git send-email --to=git@vger.kernel.org --cc=j6t@kdbg.org *.patch
> +```
> +
> +For `git send-email` configuration, see the [documentation](https://git-scm.com/docs/git-send-email) (search for "Examples of SMTP Servers").
> +
> +For information about subscribing to the Git mailing list, see [subscription info](https://git.wiki.kernel.org/index.php/GitCommunity). Note that subscription is not required to participate in patch discussions.
> +
> +### GitHub Pull Requests
> +- Fork this repository and create a feature branch
> +- Submit a pull request with a clear description of your changes
> +
> +## Building
> +
> +gitk is a Tcl/Tk application. It requires Tcl/Tk to be installed on your system.
> +
> +### Running directly
> +```bash
> +./gitk
> +```
> +
> +### Installation
> +To install system-wide, you can use either `make` or `meson`:
> +
> +```bash
> +# Using Make
> +make install
> +
> +# Using Meson
> +meson setup builddir
> +meson compile -C builddir
> +meson install -C builddir
> +```
> +
> +Both build systems will handle setting the correct Tcl/Tk interpreter path and installing translation files.
> +
> +## License
> +
> +gitk is distributed under the GNU General Public License, either version 2, or (at your option) any later version.
> \ No newline at end of file
Michael Rappazzo
