← Back to team overview

kicad-developers team mailing list archive

Re: Update of KiCad documentation?

 

A URL into the documentation would probably lessen the friction of locating exactly what section of documentation needs fixing. Dev's changing user facing stuff will be familiar with (if not actively stubbing out, or updating the docs) it so it seems a reasonable ask.

CHANGED: Synopsis. url#section

Consider just one keyword (CHANGE, or FEATURE) so we are not doing "git log --grep=CHANGE|NEW|REMOVED"

On 10/11/17 05:44, Wayne Stambaugh wrote:
I like this idea as well.  It's simple and easy to remember.  If there
are no objections, I will updated the commit message policy to add NEW,
CHANGED, and REMOVED tags and a brief explanation of when each tag
should be used.  Is there any special formatting that we want to use
with these tags to make life easier for folks trying to extract
information using scripts?  Rather than adding the tag to the end which
may be a bit limiting, I was thinking it may make more sense to add the
tag to the beginning of the description of the change separated by empty
lines.  It could look something like this.

Major rewrite of some existing feature.

NEW: The feature adds support for X, Y, and Z operations.

REMOVED: The feature no longer supports the foo operation.

CHANGED: The feature operations bar and baz now require manual frobnication.

If anyone has any better ideas, now is the time.

Cheers,

Wayne

On 11/9/2017 11:06 AM, Maciej Sumiński wrote:
I am in favor of including the information in commit messages. In the
simplest version, one can simple append "CHANGE" at the end of a commit
message. If we follow this scheme, then to get a changelog it is enough
to execute "git log --grep=CHANGE". One can also modify the query to get
changelog for different periods.

It is a tiny effort on the developers side which significantly helps
people willing to work on the documentation, therefore I think it is
worth pursuing. The only possible problem I see here is to get into the
habit, but we did well with "Fixes".

Regards,
Orson

On 11/09/2017 01:40 PM, Nick Østergaard wrote:
I didn't mean to indicate that one shall not write useful commit messages
in the kicad source repo. The start of this topic was how to make sure to
keep the doc up to date. This is what I was trying to comment on. Here it
is better to track the work where it is to be done, in the kicad-doc repo.
That does not hinder anyone from grepping the kicad commit log for new
features, when one gets the urge to create documentation. This shall of
course not hinder anyone who submits a feature to kicad to also submit
documentation updates for it either.

When we release I expect a release note to be composed that will describe
the new features as we did with http://kicad-pcb.org/post/release-4.0.0/

2017-11-09 12:39 GMT+01:00 Kristoffer Ödmark <kristofferodmark90@xxxxxxxxx>:

That doesnt sound like a good idea, when adding patches, just having to
add a line or two to the commit message seems best, and I imagine the news
or changelog file is just there to later help the kicad-doc repo to do a
proper changelog. Having to go to a new repo seems a bit more annoying.

Or skip the file totally this time, and just enfore the commit messages.
This way this will not be such a hassle next time one wonders what have
changed between versions.

On 11/09/2017 11:05 AM, Nick Østergaard wrote:

I think this might be better handled as bugs on the kicad-doc repo. Then
everyone can contribute easily and we can track it for the documentation,
where the info is to be used anyways. For now label them new_kicad_feature
if it is.

2017-11-09 10:54 GMT+01:00 Kristoffer Ödmark <
kristofferodmark90@xxxxxxxxx <mailto:kristofferodmark90@xxxxxxxxx>>:


     I think for this to start happen, a decision has to be made, and
     enforced by everyone with commit access to the repo.

     Bugfixes need not be tagged like this. Major changes only.

     I still think a we should start collect a list in the repo with
     changes from kicad 4 up to the point this commit message policy is
     set. I for one love reading changelogs when upgrading, and I think
     the users are expecting this as well, and it probably will be useful
     in the FOSDEM presentation :)


     On 11/04/2017 01:53 AM, Wayne Stambaugh wrote:

         On 11/3/2017 8:54 AM, Maciej Sumiński wrote:

             On 11/03/2017 11:30 AM, Kristoffer Ödmark wrote:

                 I think starting small would be best in this case. The
                 least needed
                 would be a "News" File, that is always refering to kicad
                 stable.

                 I propose the same way that patches with policy errors
                 are rejected,
                 patches that introduces new functionality or change of
                 existing
                 functionality are required to add to the News file, max
                 one line. Just
                 something like this, I would like markdown formatting.


                 Changes from Kicad 4
                 =

                 NEW: Pcbnew now supports clipboard copy/paste
                 CHANGE: Delete button now removes entire trace, not just
                 a segment
                 CHANGE: Icons in toolbar are improved
                 REMOVED: Autorouter no longer exists


                 This style could also be applied in the git commit
                 message, making it
                 easy to compile by something such as 'git log | grep
"NEW:"'

                 But since that is lacking, I think starting a new file
                 is best.


             I vote for git commit messages following a specific format
             (could be
             NEW:/CHANGE:/REMOVE: lines) to easily create change logs. It
             is much
             easier to see with git what has changed in a specific period
             of time.
             With NEWS file you would need at least put dates there to be
             able to do
             that (or see with git when a specific line has been added).

             I know that ideally the user documentation should be updated
             together
             with the code, but on the other KiCad changes so fast, so
             there might be
             a lot of wasted time spent on changing the documentation and
             updating
             screens that might be invalid in a week or two. For sure the
             documentation should be refreshed for a stable release.

             Regards,
             Orson


         I'm not opposed to this idea but it should be used sensibly.
    Not all
         new, changed, or removed code will require documentation
changes.  I
         would also prefer it not be in the first line of the commit
message
         unless the commit message is only one line.  It's already
         difficult to
         fit a descriptive commit title with only 72 characters.

         Cheers,

         Wayne

         _______________________________________________
         Mailing list: https://launchpad.net/~kicad-developers
         <https://launchpad.net/~kicad-developers>
         Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
         <mailto:kicad-developers@xxxxxxxxxxxxxxxxxxx>
         Unsubscribe : https://launchpad.net/~kicad-developers
         <https://launchpad.net/~kicad-developers>
         More help   : https://help.launchpad.net/ListHelp
         <https://help.launchpad.net/ListHelp>


     --       -Kristoffer


     _______________________________________________
     Mailing list: https://launchpad.net/~kicad-developers
     <https://launchpad.net/~kicad-developers>
     Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
     <mailto:kicad-developers@xxxxxxxxxxxxxxxxxxx>
     Unsubscribe : https://launchpad.net/~kicad-developers
     <https://launchpad.net/~kicad-developers>
     More help   : https://help.launchpad.net/ListHelp
     <https://help.launchpad.net/ListHelp>



--
  -Kristoffer



_______________________________________________
Mailing list: https://launchpad.net/~kicad-developers
Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
Unsubscribe : https://launchpad.net/~kicad-developers
More help   : https://help.launchpad.net/ListHelp




_______________________________________________
Mailing list: https://launchpad.net/~kicad-developers
Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
Unsubscribe : https://launchpad.net/~kicad-developers
More help   : https://help.launchpad.net/ListHelp

_______________________________________________
Mailing list: https://launchpad.net/~kicad-developers
Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
Unsubscribe : https://launchpad.net/~kicad-developers
More help   : https://help.launchpad.net/ListHelp




Follow ups

References