[PATCH gitk] gitk: add README.md with contribution guidelines

[PATCH gitk] gitk: add README.md with contribution guidelines

[Michael Rappazzo]

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
-- 
2.51.0

Re: [PATCH gitk] gitk: add README.md with contribution guidelines

[Junio C Hamano]

Michael Rappazzo <rappazzo@gmail.com> writes:

> +#### 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
> +```

Just being curious, but does the project strongly discourage a
multi-patch topic?

It would be really nice if you add "review them here before you run
send-email" step between these two commands ;-).

Thanks.

Re: [PATCH gitk] gitk: add README.md with contribution guidelines

[Mike Rappazzo]

On Wed, Aug 20, 2025 at 4:57 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Michael Rappazzo <rappazzo@gmail.com> writes:
>
> > +#### 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
> > +```
>
> Just being curious, but does the project strongly discourage a
> multi-patch topic?

I don't believe so.  I think most people know how to submit a github
PR, but J6t has mentioned that he prefers the mailing list (as noted
in the readme).  So I wrote a simple example to show that patching by
email doesn't have to be scary.

>
> It would be really nice if you add "review them here before you run
> send-email" step between these two commands ;-).

I can revise.  I will wait for more comments before sending a v2.

Re: [PATCH gitk] gitk: add README.md with contribution guidelines

[Kristoffer Haugsbakk]

On Wed, Aug 20, 2025, at 22:57, Junio C Hamano wrote:
> Michael Rappazzo <rappazzo@gmail.com> writes:
>
>> +#### 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
>> +```
>
> Just being curious, but does the project strongly discourage a
> multi-patch topic?
>
> It would be really nice if you add "review them here before you run
> send-email" step between these two commands ;-).

I alwyays use

    git format-patch ... -opatchez
    cat patchez/* | less

Because sending out something weird to a mailing list gives me the
chills.  (And there might be format-patch bugs.)

-- 
Kristoffer Haugsbakk

Re: [PATCH gitk] gitk: add README.md with contribution guidelines

[Junio C Hamano]

Mike Rappazzo <rappazzo@gmail.com> writes:

> On Wed, Aug 20, 2025 at 4:57 PM Junio C Hamano <gitster@pobox.com> wrote:
>>
>> Michael Rappazzo <rappazzo@gmail.com> writes:
>>
>> > +#### 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
>> > +```
>>
>> Just being curious, but does the project strongly discourage a
>> multi-patch topic?
>
> I don't believe so.  I think most people know how to submit a github
> PR, but J6t has mentioned that he prefers the mailing list (as noted
> in the readme).  So I wrote a simple example to show that patching by
> email doesn't have to be scary.

As the original assumes that you are on the branch where you are
taking the patch(es) from, perhaps

    $ git format-patch --subject-prefix='PATCH gitk' @{u}..

would work?  I was mostly reacting to the "-1" on the command line.

>> It would be really nice if you add "review them here before you run
>> send-email" step between these two commands ;-).
>
> I can revise.  I will wait for more comments before sending a v2.

Thanks.

Re: [PATCH gitk] gitk: add README.md with contribution guidelines

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

>> It would be really nice if you add "review them here before you run
>> send-email" step between these two commands ;-).
>
> I alwyays use
>
>     git format-patch ... -opatchez
>     cat patchez/* | less
>
> Because sending out something weird to a mailing list gives me the
> chills.  (And there might be format-patch bugs.)

Thanks for a tip.

It matches what I do, except that I use ./+jc/<topic-name>/
directories as the staging area, as I tend to keep what I sent out
for a few days, and I strongly prefer to give its own directory to
each topic, to avoid "git send-email *.patch" sending out random
unrelated patches.

Re: [PATCH gitk] gitk: add README.md with contribution guidelines

[Mike Rappazzo]

On Wed, Aug 20, 2025 at 5:12 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Mike Rappazzo <rappazzo@gmail.com> writes:
>
> > On Wed, Aug 20, 2025 at 4:57 PM Junio C Hamano <gitster@pobox.com> wrote:
> >>
> >> Michael Rappazzo <rappazzo@gmail.com> writes:
> >>
> >> > +#### 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
> >> > +```
> >>
> >> Just being curious, but does the project strongly discourage a
> >> multi-patch topic?
> >
> > I don't believe so.  I think most people know how to submit a github
> > PR, but J6t has mentioned that he prefers the mailing list (as noted
> > in the readme).  So I wrote a simple example to show that patching by
> > email doesn't have to be scary.
>
> As the original assumes that you are on the branch where you are
> taking the patch(es) from, perhaps
>
>     $ git format-patch --subject-prefix='PATCH gitk' @{u}..
>
> would work?  I was mostly reacting to the "-1" on the command line.

`@{u}..` is funny, because that seems to assume that you haven't
pushed your changes to its upstream yet.  I could say `master..` but
that assumes that you named the branch that (as opposed to `main` or
something).  I will try a few different ways and see how they feel.
As I said, I just wanted an example to demystify patching by email.  I
think if I add something above to clarify that this is just an example
and not verbose instructions it could help too.

>
> >> It would be really nice if you add "review them here before you run
> >> send-email" step between these two commands ;-).
> >
> > I can revise.  I will wait for more comments before sending a v2.
>
> Thanks.

Re: [PATCH gitk] gitk: add README.md with contribution guidelines

[D. Ben Knoble]

On Wed, Aug 20, 2025 at 5:20 PM Mike Rappazzo <rappazzo@gmail.com> wrote:
>
> On Wed, Aug 20, 2025 at 5:12 PM Junio C Hamano <gitster@pobox.com> wrote:
> >
> > Mike Rappazzo <rappazzo@gmail.com> writes:
> >
> > > On Wed, Aug 20, 2025 at 4:57 PM Junio C Hamano <gitster@pobox.com> wrote:
> > >>
> > >> Michael Rappazzo <rappazzo@gmail.com> writes:
> > >>
> > >> > +#### 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
> > >> > +```
> > >>
> > >> Just being curious, but does the project strongly discourage a
> > >> multi-patch topic?
> > >
> > > I don't believe so.  I think most people know how to submit a github
> > > PR, but J6t has mentioned that he prefers the mailing list (as noted
> > > in the readme).  So I wrote a simple example to show that patching by
> > > email doesn't have to be scary.
> >
> > As the original assumes that you are on the branch where you are
> > taking the patch(es) from, perhaps
> >
> >     $ git format-patch --subject-prefix='PATCH gitk' @{u}..
> >
> > would work?  I was mostly reacting to the "-1" on the command line.
>
> `@{u}..` is funny, because that seems to assume that you haven't
> pushed your changes to its upstream yet.  I could say `master..` but
> that assumes that you named the branch that (as opposed to `main` or
> something).  I will try a few different ways and see how they feel.
> As I said, I just wanted an example to demystify patching by email.  I
> think if I add something above to clarify that this is just an example
> and not verbose instructions it could help too.

It is less funny when @{u} is the branch you started your work from
and where you hope to integrate to, as in

    git switch -c topic origin/master

or something.

Then, you might use @{push} to refer to that "somewhere else" you push
to that is not the place to which you hope your changes will go. It is
certainly different from lots of GitHub- and similar tutorials that
encourage "git push -u <remote> <branch>," which sets @{upstream} to
what I prefer to use @{push} for. Granted, those tutorials use
something closer to a centralized workflow, and what I'm describing
(what mailing list flows are?) is more triangular.

> > >> It would be really nice if you add "review them here before you run
> > >> send-email" step between these two commands ;-).
> > >
> > > I can revise.  I will wait for more comments before sending a v2.

Linking to https://git-send-email.io/ is probably the best advice on
making sending patches less scary.

-- 
D. Ben Knoble

Re: [PATCH gitk] gitk: add README.md with contribution guidelines

[Johannes Sixt]

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:
> 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