Subject: Missing COMMENT ON POLICY

From: "Charles Clavadetscher" <[email-masked]>
Date: Sun, 13 Sep 2015 07:36:14 +0200

Hello

Lately I am working intensively with the documentation capabilities of
PostgreSQL and I noticed that, although the functionality is available in
9.5 to add a comment to a policy, there is no entry for in the documentation

http://www.postgresql.org/docs/9.5/static/sql-comment.html

Probably it would look like:

COMMENT ON POLICY policy_name ON table_name |

Between
OPERATOR FAMILY object_name USING index_method | and
[ PROCEDURAL ] LANGUAGE object_name |
 
Regards
Charles

-- 
Sent via pgsql-docs mailing list ([email-masked])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

---

From: "Charles Clavadetscher" <[email-masked]>
Date: Sun, 13 Sep 2015 08:21:55 +0200

Hello

Well I gave it a try. I am still not very well aware how the process for
suggesting or submitting corrections work, but this is as far as I got.
In the attachment is a patch for the missing entry for POLICY in the
documentation on COMMENT that I mentioned earlier on pgsql-docs.

Hope this helps.

Regards
Charles

-----Original Message-----
From: [email-masked]
[mailto:[email-masked]] On Behalf Of Charles Clavadetscher
Sent: Sonntag, 13. September 2015 07:36
To: [email-masked]
Subject: [DOCS] Missing COMMENT ON POLICY

Hello

Between
 
Regards
Charles

-- 
Sent via pgsql-hackers mailing list ([email-masked])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

---

From: Stephen Frost <[email-masked]>
Date: Sun, 13 Sep 2015 08:30:38 -0400

Charles,

> documentation on COMMENT that I mentioned earlier on pgsql-docs.

Thanks!  This looks mostly correct but only goes half-way (not that
there's a lot to this change ;).  The 'policy_name' parameter which is
added should also be added to the 'Parameters' list below, and the
description under 'table_name' updated to reflect that it's used for
policies also.

There should probably be an example added also, since it looks like
there are examples of pretty much all the other COMMENT ON
types.

Thanks again!

Stephen

---

From: "Charles Clavadetscher" <[email-masked]>
Date: Sun, 13 Sep 2015 14:42:24 +0200

Hello Stephen

Yes, of course. I will take care of that and send a new patch.
Who will then git push it?

Thank you for your feedback.
Bye
Charles

> From: [email-masked] [mailto:pgsql-hackers-
> [email-masked]] On Behalf Of Stephen Frost
> Sent: Sonntag, 13. September 2015 14:31
> To: Charles Clavadetscher <[email-masked]>
> Cc: [email-masked]
> Subject: Re: [HACKERS] [DOCS] Missing COMMENT ON POLICY
> 
> Charles,
>

---

From: Stephen Frost <[email-masked]>
Date: Sun, 13 Sep 2015 08:49:34 -0400

Charles,

Just FYI, on these lists, we'd prefer it if you wouldn't top-post.

> Yes, of course. I will take care of that and send a new patch.

Thanks!

> Who will then git push it?

I'd be happy to take care of it, though any of the committers may pick
it up, of course.  If there's a concern about the patch being missed or
forgotten then it can be added to the commitfest system (here:
http://commitfest.postgresql.org).  I don't believe there's a risk of
that here, but you're welcome to add it if you'd like, of course.

> Thank you for your feedback.

Thank you for working on this!

Stephen

---

From: Charles Clavadetscher <[email-masked]>
Date: Sun, 13 Sep 2015 15:26:58 +0200

Hello Stephen

> Thank you for working on this!
In the attachement the new patch. I was not able to create one with both 
commits so I also added the first one.
I think that documentation should be as complete as possible, but if you 
say that there is no risk in missing the update, then I don't see a need 
to add a line in the commitfest.

Thank you also for the hint on top-posting. I was not aware of that.
Have a good Sunday.
Charles

---

From: Charles Clavadetscher <[email-masked]>
Date: Sun, 13 Sep 2015 16:25:53 +0200

Stephen

> Thank you also for the hint on top-posting. I was not aware of that.

I noticed that the position of the parameter "policy_name" in the 
description list of parameters was not at the (alphabetically) correct 
position. I changed that and the result is attached.

I think/hope that is now all correct.

Thank you and bye
Charles

---

From: Stephen Frost <[email-masked]>
Date: Sun, 13 Sep 2015 10:56:05 -0400

Charles,

* Charles Clavadetscher ([email-masked]) wrote:
> description list of parameters was not at the (alphabetically)
> correct position. I changed that and the result is attached.

Thanks!

> I think/hope that is now all correct.

We generally prefer one complete patch which represents the total set
of changes to a lot of individual little patches which build on each
other.

If you're using git and have these patches on a branch as different
commits, you can do an interactive rebase to squash them all together,
like this:

git rebase -i

That will open an editor and then you can choose the action to take for
each patch.  Generally, I'll make the first patch 'reword' and the
rest 'squash'.  Saving and exiting the editor will then take you to
another editor session where you'll have an opportunity to reword the
commit message (to incorporate all of the changes).

Once all of that's done, you can use 'git format-patch' to create a file
which includes the commit message and the patch.  I generally run it
like so:

git format-patch @{u} --stdout > ~/patches/filename-for-patch.patch

Hopefully that helps.

Thanks!

Stephen

---

From: Charles Clavadetscher <[email-masked]>
Date: Sun, 13 Sep 2015 18:35:49 +0200

Hi Stephen

> git format-patch @{u} --stdout > ~/patches/filename-for-patch.patch

Yes, that helped a lot! In the attachment now a single patch file with 
all changes.

Thank you a lot. BTW, looking forward to the server programming workshop 
in Vienna.

Bye
Charles

---

From: Stephen Frost <[email-masked]>
Date: Tue, 15 Sep 2015 11:13:37 -0400

Charles,

* Charles Clavadetscher ([email-masked]) wrote:
> Yes, that helped a lot! In the attachment now a single patch file
> with all changes.

I've pushed this fix now.

Thanks!

Stephen

---

From: Charles Clavadetscher <[email-masked]>
Date: Tue, 15 Sep 2015 17:46:50 +0200

Hi Stephen

> On 15.09.2015, at 17:13, Stephen Frost <[email-masked]> wrote:
> 
> Charles,
> 

Thanks, too
Charles