← Back to team overview

kicad-developers team mailing list archive

Re: Update of KiCad documentation?

 

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


Follow ups

References