Re: [PATCH v2 2/2] patman: Add documentation to doc/
Hi Ralph, On Mon, 15 Aug 2022 at 08:41, Ralph Siemsen wrote: > > Hello Heinrich, > > FYI, I had some trouble trying to apply your changes (patch seems to > be mangled?). > > Only one small question for you, see below. > > On Wed, Aug 10, 2022 at 2:42 AM Heinrich Schuchardt > wrote: > > > > diff --git a/tools/patman/patman.rst b/tools/patman/patman.rst > > index 52151f6f16..f2e6d7636f 100644 > > --- a/tools/patman/patman.rst > > +++ b/tools/patman/patman.rst > > @@ -1,19 +1,31 @@ > > .. SPDX-License-Identifier: GPL-2.0+ > > .. Copyright (c) 2011 The Chromium OS Authors > > +.. Simon Glass > > +.. v1, v2, 19-Oct-11 > > +.. revised v3 24-Nov-11 > > +.. revised v4 04-Jul-2020, with Patchwork integration > > > > Patman patch manager > > > > > > This tool is a Python script which: > > + > > - Creates patch directly from your branch > > + > > - Cleans them up by removing unwanted tags > > + > > - Inserts a cover letter with change lists > > + > > - Runs the patches through checkpatch.pl and its own checks > > + > > - Optionally emails them out to selected people > > > > It also has some Patchwork features: > > + > > - shows review tags from Patchwork so you can update your local patches > > + > > - pulls these down into a new branch on request > > + > > - lists comments received on a series > > > > It is intended to automate patch creation and make it a less > > @@ -41,12 +53,15 @@ This tool requires a certain way of working: > > > > - Maintain a number of branches, one for each patch series you are > > working on > > + > > - Add tags into the commits within each branch to indicate where the > > series should be sent, cover letter, version, etc. Most of these are > > normally in the top commit so it is easy to change them with 'git > > commit --amend' > > + > > - Each branch tracks the upstream branch, so that this script can > > automatically determine the number of commits in it (optional) > > + > > - Check out a branch, and run this script to create and send out your > > patches. Weeks later, change the patches and repeat, knowing that you > > will get a consistent result each time. > > Is it necessary to have a blank line between each of the "bullet" > points? It seems to work fine as long as there is one blank line > separating the paragraph from the first bullet item. It seems not, I will take a look. > > Otherwise, it looks good to me. Regards, Simon
Re: [PATCH v2 2/2] patman: Add documentation to doc/
Hello Heinrich, FYI, I had some trouble trying to apply your changes (patch seems to be mangled?). Only one small question for you, see below. On Wed, Aug 10, 2022 at 2:42 AM Heinrich Schuchardt wrote: > > diff --git a/tools/patman/patman.rst b/tools/patman/patman.rst > index 52151f6f16..f2e6d7636f 100644 > --- a/tools/patman/patman.rst > +++ b/tools/patman/patman.rst > @@ -1,19 +1,31 @@ > .. SPDX-License-Identifier: GPL-2.0+ > .. Copyright (c) 2011 The Chromium OS Authors > +.. Simon Glass > +.. v1, v2, 19-Oct-11 > +.. revised v3 24-Nov-11 > +.. revised v4 04-Jul-2020, with Patchwork integration > > Patman patch manager > > > This tool is a Python script which: > + > - Creates patch directly from your branch > + > - Cleans them up by removing unwanted tags > + > - Inserts a cover letter with change lists > + > - Runs the patches through checkpatch.pl and its own checks > + > - Optionally emails them out to selected people > > It also has some Patchwork features: > + > - shows review tags from Patchwork so you can update your local patches > + > - pulls these down into a new branch on request > + > - lists comments received on a series > > It is intended to automate patch creation and make it a less > @@ -41,12 +53,15 @@ This tool requires a certain way of working: > > - Maintain a number of branches, one for each patch series you are > working on > + > - Add tags into the commits within each branch to indicate where the > series should be sent, cover letter, version, etc. Most of these are > normally in the top commit so it is easy to change them with 'git > commit --amend' > + > - Each branch tracks the upstream branch, so that this script can > automatically determine the number of commits in it (optional) > + > - Check out a branch, and run this script to create and send out your > patches. Weeks later, change the patches and repeat, knowing that you > will get a consistent result each time. Is it necessary to have a blank line between each of the "bullet" points? It seems to work fine as long as there is one blank line separating the paragraph from the first bullet item. Otherwise, it looks good to me. Ralph
Re: [PATCH v2 2/2] patman: Add documentation to doc/
Hi Heinrich,
On Wed, 10 Aug 2022 at 00:47, Heinrich Schuchardt wrote:
>
> On 8/9/22 21:49, Simon Glass wrote:
> > Link to patman's documentation from the doc/ directory so that it appears
> > in the 'make htmldocs' output.
> >
> > Signed-off-by: Simon Glass
> > ---
> >
> > Changes in v2:
> > - Fix up access to help from patman tool
> >
> > doc/develop/index.rst | 1 +
> > doc/develop/patman.rst | 1 +
> > doc/develop/sending_patches.rst | 16 +
> > tools/patman/README.rst | 1 +
> > tools/patman/main.py| 3 +-
> > tools/patman/{README => patman.rst} | 526 ++--
> > 6 files changed, 287 insertions(+), 261 deletions(-)
> > create mode 12 doc/develop/patman.rst
> > create mode 100644 doc/develop/sending_patches.rst
> > create mode 12 tools/patman/README.rst
> > rename tools/patman/{README => patman.rst} (52%)
> >
> > diff --git a/doc/develop/index.rst b/doc/develop/index.rst
> > index 7c41e3f1b6e..7476f9ca0eb 100644
> > --- a/doc/develop/index.rst
> > +++ b/doc/develop/index.rst
> > @@ -14,6 +14,7 @@ General
> > process
> > release_cycle
> > system_configuration
> > + sending_patcheshis
> >
> > Implementation
> > --
> > diff --git a/doc/develop/patman.rst b/doc/develop/patman.rst
> > new file mode 12
> > index 000..0fcb7d61d40
> > --- /dev/null
> > +++ b/doc/develop/patman.rst
> > @@ -0,0 +1 @@
> > +../../tools/patman/patman.rst
> > \ No newline at end of file
> > diff --git a/doc/develop/sending_patches.rst
> > b/doc/develop/sending_patches.rst
> > new file mode 100644
> > index 000..0542adeaed9
> > --- /dev/null
> > +++ b/doc/develop/sending_patches.rst
>
> Thanks for moving this to the HTML documentation.
>
> This files contains numerous formatting errors which are not covered by
> your diff. It is worthwhile to look at the output of 'make htmldocs'.
Yes that's how I found the problems, but clearly not all of them and I
have not bothered with the bash code-block thing. I will start using
it more.
>
> May I apply the following when merging?
Yes, thanks.
>
> Do we need the incomplete changelog?
I prefer to keep it.
>
> By the way, Independence Day 2020 depends on the country the reader
> lives in, August 15th in India.
Thanks for the info but I don't live in India :-)
Regards,
Simon
Re: [PATCH v2 2/2] patman: Add documentation to doc/
On 8/9/22 21:49, Simon Glass wrote:
Link to patman's documentation from the doc/ directory so that it appears
in the 'make htmldocs' output.
Signed-off-by: Simon Glass
---
Changes in v2:
- Fix up access to help from patman tool
doc/develop/index.rst | 1 +
doc/develop/patman.rst | 1 +
doc/develop/sending_patches.rst | 16 +
tools/patman/README.rst | 1 +
tools/patman/main.py| 3 +-
tools/patman/{README => patman.rst} | 526 ++--
6 files changed, 287 insertions(+), 261 deletions(-)
create mode 12 doc/develop/patman.rst
create mode 100644 doc/develop/sending_patches.rst
create mode 12 tools/patman/README.rst
rename tools/patman/{README => patman.rst} (52%)
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 7c41e3f1b6e..7476f9ca0eb 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -14,6 +14,7 @@ General
process
release_cycle
system_configuration
+ sending_patcheshis
Implementation
--
diff --git a/doc/develop/patman.rst b/doc/develop/patman.rst
new file mode 12
index 000..0fcb7d61d40
--- /dev/null
+++ b/doc/develop/patman.rst
@@ -0,0 +1 @@
+../../tools/patman/patman.rst
\ No newline at end of file
diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
new file mode 100644
index 000..0542adeaed9
--- /dev/null
+++ b/doc/develop/sending_patches.rst
Thanks for moving this to the HTML documentation.
This files contains numerous formatting errors which are not covered by
your diff. It is worthwhile to look at the output of 'make htmldocs'.
May I apply the following when merging?
Do we need the incomplete changelog?
By the way, Independence Day 2020 depends on the country the reader
lives in, August 15th in India.
Best regards
Heinrich
diff --git a/tools/patman/patman.rst b/tools/patman/patman.rst
index 52151f6f16..f2e6d7636f 100644
--- a/tools/patman/patman.rst
+++ b/tools/patman/patman.rst
@@ -1,19 +1,31 @@
.. SPDX-License-Identifier: GPL-2.0+
.. Copyright (c) 2011 The Chromium OS Authors
+.. Simon Glass
+.. v1, v2, 19-Oct-11
+.. revised v3 24-Nov-11
+.. revised v4 04-Jul-2020, with Patchwork integration
Patman patch manager
This tool is a Python script which:
+
- Creates patch directly from your branch
+
- Cleans them up by removing unwanted tags
+
- Inserts a cover letter with change lists
+
- Runs the patches through checkpatch.pl and its own checks
+
- Optionally emails them out to selected people
It also has some Patchwork features:
+
- shows review tags from Patchwork so you can update your local patches
+
- pulls these down into a new branch on request
+
- lists comments received on a series
It is intended to automate patch creation and make it a less
@@ -41,12 +53,15 @@ This tool requires a certain way of working:
- Maintain a number of branches, one for each patch series you are
working on
+
- Add tags into the commits within each branch to indicate where the
series should be sent, cover letter, version, etc. Most of these are
normally in the top commit so it is easy to change them with 'git
commit --amend'
+
- Each branch tracks the upstream branch, so that this script can
automatically determine the number of commits in it (optional)
+
- Check out a branch, and run this script to create and send out your
patches. Weeks later, change the patches and repeat, knowing that you
will get a consistent result each time.
@@ -117,21 +132,25 @@ project you can add a section that looks like
[project_settings] or
How to run it
-
-First do a dry run::
+First do a dry run:
-$ ./tools/patman/patman send -n
+.. code-block:: bash
+
+./tools/patman/patman send -n
If it can't detect the upstream branch, try telling it how many patches
-there are in your series::
+there are in your series
+
+.. code-block:: bash
-$ ./tools/patman/patman -c5 send -n
+./tools/patman/patman -c5 send -n
This will create patch files in your current directory and tell you who
-it is thinking of sending them to. Take a look at the patch files
+it is thinking of sending them to. Take a look at the patch files:
-::
+.. code-block:: bash
-$ ./tools/patman/patman -c5 -s1 send -n
+./tools/patman/patman -c5 -s1 send -n
Similar to the above, but skip the first commit and take the next 5. This
is useful if your top commit is for setting up testing.
@@ -143,9 +162,11 @@ How to install it
The most up to date version of patman can be found in the U-Boot sources.
However to use it on other projects it may be more convenient to
install it as
a standalone application. A distutils installer is included, this can
be used
-to install patman::
+to install patman:
-$ cd tools/patman && python setup.py install
+.. code-block:: bash
+
+cd tools/patman && python setup.py install
How to add tags
@@ -191,6
[PATCH v2 2/2] patman: Add documentation to doc/
Link to patman's documentation from the doc/ directory so that it appears
in the 'make htmldocs' output.
Signed-off-by: Simon Glass
---
Changes in v2:
- Fix up access to help from patman tool
doc/develop/index.rst | 1 +
doc/develop/patman.rst | 1 +
doc/develop/sending_patches.rst | 16 +
tools/patman/README.rst | 1 +
tools/patman/main.py| 3 +-
tools/patman/{README => patman.rst} | 526 ++--
6 files changed, 287 insertions(+), 261 deletions(-)
create mode 12 doc/develop/patman.rst
create mode 100644 doc/develop/sending_patches.rst
create mode 12 tools/patman/README.rst
rename tools/patman/{README => patman.rst} (52%)
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 7c41e3f1b6e..7476f9ca0eb 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -14,6 +14,7 @@ General
process
release_cycle
system_configuration
+ sending_patches
Implementation
--
diff --git a/doc/develop/patman.rst b/doc/develop/patman.rst
new file mode 12
index 000..0fcb7d61d40
--- /dev/null
+++ b/doc/develop/patman.rst
@@ -0,0 +1 @@
+../../tools/patman/patman.rst
\ No newline at end of file
diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
new file mode 100644
index 000..0542adeaed9
--- /dev/null
+++ b/doc/develop/sending_patches.rst
@@ -0,0 +1,16 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Sending patches
+===
+
+.. toctree::
+ :maxdepth: 2
+
+ patman
+
+
+You can use a tool called patman to prepare, check and sent patches. It creates
+change logs, cover letters and patch notes. It also simplified the process of
+sending multiple versions of a series.
+
+See more details at :doc:`patman`.
diff --git a/tools/patman/README.rst b/tools/patman/README.rst
new file mode 12
index 000..76368b95980
--- /dev/null
+++ b/tools/patman/README.rst
@@ -0,0 +1 @@
+patman.rst
\ No newline at end of file
diff --git a/tools/patman/main.py b/tools/patman/main.py
index 15e7af0e54e..5a7756a221b 100755
--- a/tools/patman/main.py
+++ b/tools/patman/main.py
@@ -164,7 +164,8 @@ elif args.cmd == 'send':
elif args.full_help:
tools.print_full_help(
-os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])),
'README')
+os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])),
+ 'README.rst')
)
else:
diff --git a/tools/patman/README b/tools/patman/patman.rst
similarity index 52%
rename from tools/patman/README
rename to tools/patman/patman.rst
index e3466e60854..52151f6f16e 100644
--- a/tools/patman/README
+++ b/tools/patman/patman.rst
@@ -1,8 +1,8 @@
-# SPDX-License-Identifier: GPL-2.0+
-# Copyright (c) 2011 The Chromium OS Authors.
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2011 The Chromium OS Authors
-What is this?
-=
+Patman patch manager
+
This tool is a Python script which:
- Creates patch directly from your branch
@@ -24,9 +24,9 @@ It is configured almost entirely by tags it finds in your
commits.
This means that you can work on a number of different branches at
once, and keep the settings with each branch rather than having to
git format-patch, git send-email, etc. with the correct parameters
-each time. So for example if you put:
+each time. So for example if you put::
-Series-to: fred.bl...@napier.co.nz
+Series-to: fred.bl...@napier.co.nz
in one of your commits, the series will be sent there.
@@ -35,30 +35,30 @@ patches automatically (unless you use -m to disable this).
How to use this tool
-
+
This tool requires a certain way of working:
- Maintain a number of branches, one for each patch series you are
-working on
+ working on
- Add tags into the commits within each branch to indicate where the
-series should be sent, cover letter, version, etc. Most of these are
-normally in the top commit so it is easy to change them with 'git
-commit --amend'
+ series should be sent, cover letter, version, etc. Most of these are
+ normally in the top commit so it is easy to change them with 'git
+ commit --amend'
- Each branch tracks the upstream branch, so that this script can
-automatically determine the number of commits in it (optional)
+ automatically determine the number of commits in it (optional)
- Check out a branch, and run this script to create and send out your
-patches. Weeks later, change the patches and repeat, knowing that you
-will get a consistent result each time.
+ patches. Weeks later, change the patches and repeat, knowing that you
+ will get a consistent result each time.
How to configure it
-===
+---
For most cases of using patman for U-Boot development, patman can use the
file 'doc/git-mailrc' in your U-Boot directory to supply the email aliases
you need.
