← Back to team overview

kicad-developers team mailing list archive

Re: A reminder on Git commit comments

 

Hello Rene,

I'm answering with a it of delay, to much to do in to less time.
We are going to be oftopic for this list and should do discussions about
these specific topics on kicad-lib-committers ... but unfortunately this
list is mostly dead and unused.

Am 03.05.2018 um 12:57 schrieb Rene Pöschl:
...
>> that's unfortunately true for most of contributors or contributions no
>> matter what kind of software or project and that's a social challenge we
>> all need to deal with.
> 
> That's the difference you miss. Software engineers are at least 
> interested in learning about version control systems. After all they can 
> use that skill in their career. Electrical engineers typically do not 
> use it.

I'm fully aware about this as I see such behavior mostly every day on my
day job. The unwillingness of some "engineers" to not use and accept a
SCM on present days is becoming a bigger problem from day to day. But
it's wrong to accept this circumstance in my eyes. If you try to ignore
this your work won't ever became easier or more productive. I see mostly
colleges that are happy to do better job if you explain and help them to
understand why they should change their workflow.

...
> Most of the open pull requests have been reviewed and a fix from the 
> contributor size is necessary.

Really?
Isn't it sometimes, I'd say mostly, not easier if you as the final
decision taking person would fix smaller things directly?
My experience in similar situations is that contributors are happy to
give a initial point or contribution but not really care how their idea
or work is added later and also doesn't care much about if their name is
listed in the contribution (for the reason you wrote above). But of
course we list the origin person behind a change.
I mean, you all as maintainers of the libraries will probably do a much
quicker job on doing the requested and needed changes on pull requests.
OTOH this means you need to break out the static GitHub WebUI.

But yes, some certain contributions are to poor or get them into a
reasonable state by yours.

...
> I know the technicalities of git. But it doesn't help much if the thing 
> you are working on is not really well suited to be handled by git.

That's what I already stated.

> A good example is that from time to time the save algorithm (of
> kicad) seems to randomly change. (Insert whites-paces where they
> never where before, change the ordering of lines, ...)

For sure true. To avoid such unneeded changes some autotests need to be
added to the KiCad builds. But $SOMEONE needs to implement this then.
Should not be that difficult to add something like this after the
successful build of KiCad in the Jenkins machinery.

> Again we are not dealing with human created text files. Merging is not 
> really possible so we loose a large part of what can be done with git. 
> (So if you have someone who knows git and git only he can do exactly 
> nothing. The person needs to be able to read kicad files.)

I think it's now clear that the current workflow to add symbols and
footprints isn't optimal and efficient. People who want's to contribute
need to have a good knowledge about KiCads internals, need to deal right
with the QS work, with git VCS commands *and* then with the GitHub PR
workflow. That's far away from easy and quick.

...
> I have for my self compiled a list of features required for any tool 
> handling the official lib:
> - We need some way of sharing the data (oviosly)
> - We need some sort of staging area for users to commit changes for 
> review (we use pull requests for this)
> - We need a way to run automatic tests on the contribution (continued 
> integration support within pull requests)
> - We need a way to share screenshots and or technical drawings (comment 
> section of the pull request)
> - We need a way to give feedback (both in text and image form -> again 
> comment section of a pull request)
> - We need a way to track what exactly the contributor changed after 
> feedback has been given (well this is where git comes in handy.)
> - And after everything is ok we need a way to get the changes into the 
> main "repo" without risking overwriting other peoples contributions. 
> (The merge step)
> 
> So yes git and github have their limitations but i can't think of a 
> better tool right now.

Agreed. But knowing what the current problems are help to look and find
a better solution. Here are some points that going around in my head for
some times now.

I was thinking about a website with some kind of back end that is using
HTML5 technology to visualize the various contributions made by
uploaders and also to get such contribution easier and quicker into
place. How could this work?

A contributor is uploading (directly from the symboleditor?) to the
WebUI. Some JS or Python voodoo is taking the upload and producing a
Canvas element that is shown on the website, no need to upload a PNG or
JPG file. A additional link to the documentation or direct uploaded PDF
file will help so have the documentation near by.

Next the KLC compliance check is running automatically and violations
are also visualized on top or on a extra generated Canvas graphic.
Ideally the WebUI is helping or guiding the uploader directly to fix KLC
issues then.

If that part is going well and the user is fine with the solution it
would go to a staging area where the maintainers come in to have a final
look at all. If it's o.k. the change will be committed into a staging
branch (aka 'next-release' or so).

This branch can be used for usual beta testing and fixing.

I believe a backend system written in Python would have the biggest
benefit as this could mostly easy interact with the existing Python API
to ensure the symbols are really usable with the current KiCad development.

That's the basic idea I have for some time about a possible workflow
without a needed direct interaction with git on a contributor side. Even
the integration of a new symbol should be done finally with the existing
Python API. I don't know in detail how useful the current Python
implementation are for this kind of use case. But for sure there exist
at least one Python library or framework for doing any HTML5 visualization.

I never have written a own Flake8 or Django Framework so I can't really
start here something new and hope that someone else would do this.

...>> This information is quite useless in the end and confusing due blowing
>> of commits and meta information by this. You need this information only
>> to decide if further changes are needed before merging or committing.
>> For me later all these changes are pointless. So please no merge commits
>> in pull requests and no further modification commits.
>>
>> For classical pull requests on mailing list this information is handled
>> in the patch itself as this text block which will not result in the
>> final git history. Looks like this
> 
> I think we speak a different language. I have no idea what you wrote above.

Hmm, then you never had to modify and extend an existing pull request on
your side to provide updated patches to projects that don't use any non
free platform like GitHub or Bitbucket and prefer patches only by email.

...
> Our typical contribution does not reference an issue. After all most 
> contributions are new "features"

Every action on GitHub is working as issue with a number and that is
fine. You probably didn't noticed that maybe. Every pull request or
issue get a separate new unique issue number like #1234. By this
uniqueness you can always reference to s specific issue.

> And even if we fix something. It is most likely not previously reported 
> in an issue but was found by the librarian shortly before committing a 
> fix. And even if there is an issue. Most of the time more than one pull 
> request is needed to really fix all facets of this issue. (we could 
> divide issues more, but then we take more time writing down issues then 
> it would take to fix them.)

You are talking about physical issues of a symbols, footprints etc. I'm
only talking about the organization of the git workflow for referencing.

...
>> Yes, at least the maintainers need to do more like this or locally on
>> their machine before doing ping pong with pull or merge request. Don't
>> get me wrong, it's awesome what the libraries have been evolved over the
>> last year. It's just a never ending task as you will find always new
>> advantages to get things improved.
>>
> Our focus will always be on the quality of the result. Not necessarily 
> on documenting how we get there.

And that will be a problem in the future I think. You need to document
what are the needed steps to get a reproducible outcome. If not all the
tedious work of reviewing the pull requests will be on to few people.
I've lost the energy and interest to contribute anything because of the
amount of work I've need to do. I simply have not the time to do so. So
I stay with local created and stored elements but that is only helping me.

-- 
Regards
Carsten Schoenert


References