all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* [Emacs-diffs] master 9ed3685a77: Lots of refactorings and a few minor improvements.
@ 2017-01-04  2:27 Tino Calancha
  2017-01-04  3:05 ` Paul Eggert
       [not found] ` <492.1483523991@eskebo.fritz.box>
  0 siblings, 2 replies; 7+ messages in thread
From: Tino Calancha @ 2017-01-04  2:27 UTC (permalink / raw)
  To: Stefan Merten; +Cc: Emacs developers, Tino Calancha


>Lots of refactorings and a few minor improvements.
>
>User visible improvements and changes:
>* Improve and debug `rst-forward-section` and `rst-backward-section`.
>* Auto-enumeration may be used with all styles for list insertion.
>* Improve and debug `rst-toc-insert`.
>* Adapt change in Emacs to use customization group `text` instead of `wp`.
>* Bind `n` and `p` in `rst-toc-mode`.
>* `z` in `toc-mode` returns to the previous window configuration.
>* Require Emacs version >= 24.1.
>
>Lots of refactorings including:
>* Silence byte compiler.
>* Use lexical binding.
>* Use `cl-lib`.
>* Add tests and raise test coverage.
This is not a standard Emacs commit message: i need to go throughout
the whole diffs to know exactly what entities have being modified.

Tino



^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [Emacs-diffs] master 9ed3685a77: Lots of refactorings and a few minor improvements.
  2017-01-04  2:27 [Emacs-diffs] master 9ed3685a77: Lots of refactorings and a few minor improvements Tino Calancha
@ 2017-01-04  3:05 ` Paul Eggert
  2017-01-04 13:56   ` Kaushal Modi
       [not found] ` <492.1483523991@eskebo.fritz.box>
  1 sibling, 1 reply; 7+ messages in thread
From: Paul Eggert @ 2017-01-04  3:05 UTC (permalink / raw)
  To: Stefan Merten; +Cc: Emacs developers, Tino Calancha

Tino Calancha wrote:

> This is not a standard Emacs commit message: i need to go throughout
> the whole diffs to know exactly what entities have being modified.

Yes. Please see the section "Commit messages" in the file CONTRIBUTING for the 
commit-message format that is preferred for Emacs changes.



^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [Emacs-diffs] master 9ed3685a77: Lots of refactorings and a few minor improvements.
  2017-01-04  3:05 ` Paul Eggert
@ 2017-01-04 13:56   ` Kaushal Modi
  0 siblings, 0 replies; 7+ messages in thread
From: Kaushal Modi @ 2017-01-04 13:56 UTC (permalink / raw)
  To: Stefan Merten; +Cc: Paul Eggert, Tino Calancha, Emacs developers

[-- Attachment #1: Type: text/plain, Size: 708 bytes --]

With these many changes, I believe it is worth to make another commit with
a proper change log as explained here:
http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE#n44

One should be able to understand which files (and functions) are touched by
that commit just by reading the commit log.

On Tue, Jan 3, 2017 at 10:05 PM Paul Eggert <eggert@cs.ucla.edu> wrote:

> Tino Calancha wrote:
>
> > This is not a standard Emacs commit message: i need to go throughout
> > the whole diffs to know exactly what entities have being modified.
>
> Yes. Please see the section "Commit messages" in the file CONTRIBUTING for
> the
> commit-message format that is preferred for Emacs changes.
>
> --

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1319 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [Emacs-diffs] master 9ed3685a77: Lots of refactorings and a few minor improvements.
       [not found]   ` <4331.1483545171@eskebo.fritz.box>
@ 2017-01-04 18:23     ` Paul Eggert
  2017-01-07 10:45       ` Refactoring in rst.el (was: Re: [Emacs-diffs] master 9ed3685a77: Lots of refactorings and a few minor improvements.) Stefan Merten
  0 siblings, 1 reply; 7+ messages in thread
From: Paul Eggert @ 2017-01-04 18:23 UTC (permalink / raw)
  To: Stefan Merten, Tino Calancha, Kaushal Modi; +Cc: Emacs Development

Stefan Merten wrote:

> I got the impression, that lately few people care about these rules

I'm afraid that impression is incorrect. Many developers care (hence this thread 
:-).

> See for example:
>
> http://git.savannah.gnu.org/cgit/emacs.git/commit/lisp/textmodes/rst.el?id=92e5b41c7c5898820356fc66456804a45bbe7852
> http://git.savannah.gnu.org/cgit/emacs.git/commit/lisp/textmodes/rst.el?id=c61ee94959ba96b2a327df0684593f7e569e30be

Those examples merely rename locals or adjust comments, and typically this 
doesn't need to be mentioned in ChangeLogs. Your changes did more than that.

> I hope the commit message below is what you require.

Much better, thanks. My main problem with it is that "Refactor by removing old 
functions, introducing new functions and change existing functions" is too 
vague. Please write for an audience that includes people who have code that 
calls (say) rst-comment-region and want to know how to adjust the code after 
your changes to the API.

At this point, by the way, the commit is done. We're talking about what you 
should do next time. (You can change the ChangeLog.3 file later if you like, but 
that's not urgent.)



^ permalink raw reply	[flat|nested] 7+ messages in thread

* Refactoring in rst.el (was: Re: [Emacs-diffs] master 9ed3685a77: Lots of refactorings and a few minor improvements.)
  2017-01-04 18:23     ` Paul Eggert
@ 2017-01-07 10:45       ` Stefan Merten
  2017-01-07 17:18         ` Refactoring in rst.el Paul Eggert
  0 siblings, 1 reply; 7+ messages in thread
From: Stefan Merten @ 2017-01-07 10:45 UTC (permalink / raw)
  To: Paul Eggert; +Cc: Kaushal Modi, Emacs Development, Tino Calancha

Hi Paul!

3 days ago Paul Eggert wrote:
> Stefan Merten wrote:
>> I got the impression, that lately few people care about these rules
> 
> I'm afraid that impression is incorrect. Many developers care (hence
> this thread :-).

Thanks for reassuring. As you can see in the log I once did care but
this time thought it is no longer worth the hassle.

>> I hope the commit message below is what you require.
> 
> Much better, thanks. My main problem with it is that "Refactor by
> removing old functions, introducing new functions and change existing
> functions" is too vague. Please write for an audience that includes
> people who have code that calls (say) rst-comment-region and want to
> know how to adjust the code after your changes to the API.

Which raises the question what the API of `rst.el` is. So far I was
convinced that nobody will use any function from `rst.el` - so I'd
think that nobody is impacted by refactoring even if I change
signatures of functions. Of course I may be wrong.

Apart from that I'd think the interactive functions are the *real*
interface of `rst.el` which is interesting. Refactoring, however, by
definition does not impact this behavior. Debugging and those minor
changes in behavior which I did during refactoring I did document,
however. Where key bindings are impacted I defined aliases for renamed
functions so older key bindings should continue to work.

In other languages you have this public / private concept. I remember
that in Emacs you started using a double dash in identifiers to mark
them private. For example

	rst-comment-region

would be part of the public interface, while

	rst--comment-region

would be an internal function not meant for public use.

Is that correct? Are the examples valid?

If so, I'd probably like to mark internal functions this way. That
would be a good idea IMHO.


						Grüße

						Stefan



^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Refactoring in rst.el
  2017-01-07 10:45       ` Refactoring in rst.el (was: Re: [Emacs-diffs] master 9ed3685a77: Lots of refactorings and a few minor improvements.) Stefan Merten
@ 2017-01-07 17:18         ` Paul Eggert
  2017-01-14 15:18           ` Stefan Merten
  0 siblings, 1 reply; 7+ messages in thread
From: Paul Eggert @ 2017-01-07 17:18 UTC (permalink / raw)
  To: Stefan Merten; +Cc: Kaushal Modi, Emacs Development, Tino Calancha

Stefan Merten wrote:

> Which raises the question what the API of `rst.el` is.

When in doubt, document the change in the ChangeLog.

> I remember
> that in Emacs you started using a double dash in identifiers to mark
> them private.

Yes. The part in front of the double-dash is the module name.

> If so, I'd probably like to mark internal functions this way. That
> would be a good idea IMHO.

Yes, that's a reasonable change. It'd be a change to the API, and should be 
documented in the ChangeLog and in any other documentation to the package.

After that happens, it's a good idea to document even changes to the internal 
API, for benefit of those maintaining the code in question.



^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Refactoring in rst.el
  2017-01-07 17:18         ` Refactoring in rst.el Paul Eggert
@ 2017-01-14 15:18           ` Stefan Merten
  0 siblings, 0 replies; 7+ messages in thread
From: Stefan Merten @ 2017-01-14 15:18 UTC (permalink / raw)
  To: Paul Eggert; +Cc: Kaushal Modi, Emacs Development, Tino Calancha

Hi Paul!

Last week (7 days ago) Paul Eggert wrote:
> Stefan Merten wrote:
>> I remember
>> that in Emacs you started using a double dash in identifiers to mark
>> them private.
[...]
>> If so, I'd probably like to mark internal functions this way. That
>> would be a good idea IMHO.
[...]
> After that happens, it's a good idea to document even changes to the
> internal API, for benefit of those maintaining the code in question.

Do you know of anybody who is maintaining the code (beyond me)?


						Grüße

						Stefan



^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2017-01-14 15:18 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-01-04  2:27 [Emacs-diffs] master 9ed3685a77: Lots of refactorings and a few minor improvements Tino Calancha
2017-01-04  3:05 ` Paul Eggert
2017-01-04 13:56   ` Kaushal Modi
     [not found] ` <492.1483523991@eskebo.fritz.box>
     [not found]   ` <4331.1483545171@eskebo.fritz.box>
2017-01-04 18:23     ` Paul Eggert
2017-01-07 10:45       ` Refactoring in rst.el (was: Re: [Emacs-diffs] master 9ed3685a77: Lots of refactorings and a few minor improvements.) Stefan Merten
2017-01-07 17:18         ` Refactoring in rst.el Paul Eggert
2017-01-14 15:18           ` Stefan Merten

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.