At home I’ve been experimenting with git, and I can manage to init a repository, add some files, make commits. Even made some branches and switched between them.
To make such a merge request, I’ve got to put some data on a visible place, and preserve the links with the rest of the KiCad project. I’ve tried this before, but get lost in tutorials that are longer then my attention span, or do not handle interactions with external repositories at all.
So now I have a very discrete example of wanting to make a merge request for a few simple icons I’ve changed.
I think the order of doing things is:
Make a copy of the KiCad repository on gitlab (Found a button for that).
Clone that repository to a local HDD.
Change the Icons.
Make a commit to my local repository.
Push that to my copy on gitlab.
Somehow make a merge request from the change on my personal copy on gitlab.
Or maybe, halfway make a branch somewhere?
Some help with getting the right steps and commands in the right order is appreciated.
As far as interaction with external repositories go, I’ve not done much more then made clones of github / gitlab.
Welcome to the club. So many people have given up contributing. Github/Gitlab are not human-friendly.
It’s for geeks only.
No normal person wants to take a two-week course just to understand the thinking behind it.
This is still relatively easy.
Early 2020 I had a bright idea to update the “Getting Started in KiCad” manual. Managed to fork it, install the whole ascii doc thing and some other external utilities, and I partially crippled the build system, so I could build for only English instead of all translations, which brought the build time down to something acceptable (few minutes If I remember well).
Then My PC died. (no data loss) but I had to install everything again, and used a different Linux distribution. I had some missing dependencies for some of the the ascii doc thing and could not get it to build anymore.
In the meantime I’d updated a few pages of the “Getting started with KiCad” guide, still waiting somewhere on my HDD.
Now getting to a merge request for some simple .svg files should be a bit easier…
From developers (or admins or tech support) point of view you are the best kind of user, the kind that does the legwork and asks informed questions.
You are pretty much there already. I only have to add 2 things:
Always make a branch for your changes. You mentioned it already and the place to do it is right before you start modifying or adding new files to your local repository. I.e. in you list it would be step 2.5.
Gitlab makes it very easy to make merge requests. When you push your branch to your fork it will give you a link right in the terminal. Navigating to the link will open a merge request form you can fill in. If you missed this link, no worries, navigate to your repository on gitlab, then in left hand menu go to Repository -> Branches and you will see a list of your branches with merge request button for each (relatively recent) branch that diverged from master.
That’s just one of the many ways to create merge request but they all go through the same form, the way I described just prefills some relevant info so saves you time.
In general my flow for contributing to any github/gitlab repo is like this:
Create a fork by clicking a button in github/gitlab UI
Checkout local copy using git. git clone <upstream repository url>
Add my fork’s url as a secondary remote. git remote add fork <fork repository url>
You can get repository urls by navigating to it in web ui and clicking clone button
Github is similar.
To avoid having to enter user credentials every time I recommend setting up key based authentication and using ssh urls for any repository you plan to push changes to. Doesn’t matter which url you use if you only read from the repository.
For every new change I make, first I checkout master branch and pull the latest changes:
git checkout master
git pull -r
Then I create a branch
git checkout -b myfeaturebranch
Do the work, commit one or more changes
<modify/add files>
git add -A # stage commits
git commit # make a commit, provide meaningful commit message
<repeat as needed>
Push the changes to my fork
git push fork
If change is ready for review I create a merge request right away (gitlab gives you a link when you push to fork). Otherwise I continue to make changes, maybe even rewrite commits or rearrange them. Sometimes I need to rebase changes
git fetch origin # download changes from upstream repository without applying them
git rebase origin/master # reapply my changes on top of latest from upstream
git push fork --force # upload my renewed branch to the fork repository
That’s pretty much it. Here are useful commands to understand what state the repository is in
git status # tells you if you are ahead/behind of the upstream, what files are modified, new or deleted
git branch -vv # what branches you have, which is active and what upstream branches they track
git remote -vv # same but for remotes
git diff # show uncommitted changes you made in a diff format
More advanced git topics like cherry-picks, interactive rebase, merge commits are not really needed in everyday use.
I didn’t reply to you, I replied to paulvdh. If it’s gobbledygook to you then it’s because you didn’t do your homework. Some KiCad users have more technical knowledge than others, I never intended to make a full tutorial for complete newbs.
Also why would I leave my basement? I’ve got cookies here and there’s COVID outside.
Jokes aside, KiCad is a complex software suite. If you intend to contribute to it you are expected to have some knowledge and familiarity with common developer tools. There are many more ways to contribute to KiCad as a whole without ever involving yourself with git, check out Seth’s post.
I apologise for the basement comment, but really: is this discussion really for a KiCAD user forum? Please look at it yourselves. It’s for developers, right?
You can talk about “users with more technical knowledge that others”, but that’s beside the point.
Complain about me all you like and hide my posts, but try taking a step back and really read this thread. And then, read the contents of the top sticky post in the forum.
See how it matches.
Neither of the users you’re replying to are members of the kicad development team (nor am I). They are users.
I think it’s appropriate content for users who want to make small contributions to the project. It may not be appropriate content for you, in which case you’re welcome not to read it
@ML9104 I’m also (still) just a KiCad user, (who happens to answer some questions on the user forum). But please do not muddy this thread further.
I asked the question here, because KiCad Developers have more important things to do than nannying starters (such as writing real code) and I expected to get enough info here.
@qu1ck, (if you read it) Thx, I’ll look into the details tomorrow.
Your choice of words gives a bad and wrong impression.
It’s true they don’t like it. But the reason is clear. You waste everyone’s time if you want to contribute and don’t coordinate it beforehand with the team. KiCad is so large and complex project that not nearly everything can be accepted. It would soon be a mess in every possible way if people would do whatever they like and all would be merged. And if people don’t ask beforehand and the requests are rejected afterwards the lead developers must deal with things which wouldn’t be accepted anyways and possibly spend more time with it, and their time is more precious than yours for the project development (sorry, but that’s how it is, really, no offense, it’s just practical).
If you are familiar enough with the code, features and the process, you can take a risk and code before you ask, but then you have really know the project beforehand. (This is my opinion, anyways. I’m not a lead developer or a developer at all.)
Also the technical (coding) guidelines must be obeyed. Anyone who has read messy code written without guidelines knows why. That’s not relevant for graphics, of course.
In addition to all the helpful command provided above, have a look into a git client. Git lists a few here: https://git-scm.com/download/gui/linux some free some paid for. The command line gives ultimate control over git but a client provides a better visualization. You can mix usage of UI client and commandline without worry.
[Message to moderator: I think this topic should be split as it is going wildly off-topic now]
@mgyger I do not believe that was the issue. I believe the lead developers even told that from a coding perspective everything was fine. The problem was a lack of communication in advance of the merge request which would have highlighted that the way you planned to implement the feature was incompatible with the goals of the project. I can see the mailing list had been mentioned to you on at least 3 occasions in the past.
As has been mentioned to you before (and stated in the contribution guidelines), if your merge request is going to be anything more than a simple bug fix, it should be discussed in the mailing list before writing any code. As eelik mentioned, lead developers’ time is precious and would be better off being spent developing new features and fixing bugs than assessing merge requests they know nothing about and have not had the opportunity to provide input on in advance.
Also you must understand that having 35 years experience in coding doesn’t mean that you can expect it to be accepted. Most lead developers (and some contributors) have that much experience (and even more) but more critically, they have significantly more experience in contributing to KiCad. This means they will know things about the overall architecture of the code and the vision for how it will change over time that you wouldn’t know about unless you have a discussion in advance.
In addition to the discussion that needs to happen in advance of writing code to ensure alignment with the project’s goals, once you do actually write code and submit a merge request you should expect a thorough code review which will most likely require you to make changes to the code: some minor (like code formatting) and others a bit more involved (like adding new test suites).
I’m not a lead developer but have found it very rewarding to contribute to KiCad and tried my best to keep the lead developers happy. I isn’t rocket science, just good communication and respect.
Splitting into what?
I thought about it yesterday… but it would have meant heavy editing for nothing IMHO and then I got a 2-3 post thread about git and another full of stuff that has no relevance to anything on here anymore.
The main question had been answered and the community reacted cool about some hot-head and posted the ‘guidelines’ of how they think this place is supposed to work and run.
So the only choice here really was or still is leaving everything or deleting all but post #1 and #5, but losing the communities record of what they want this place to be?!
Git and pull requests have enabled a level of collaboration that was previously not possible. With one of my customers, I’ve been exploring involving more than just the programmers in managing documentation in Git – see this thought exercise.
In training people to use Git – the first week they typically complain how hard it is, and then they go silent, and after a few more weeks, it is an indispensable tool.
Git is worth learning well, because innovation often requires collaboration, and collaboration works best if it is open, inclusive, and supported by good workflow and tools.
I would agree but only if you swap git for version control. Git is great source and version control tool but it’s designed for developers. It’s not easy to really understand, hard to master and it’s documentation is deservedly the butt of jokes like this.
For non-source code use cases there may be better version control tools like svn or fossil. So shop around before you commit to git (pun intended).
Tools like GitKraken makes Git fun and easy to use. Also it is free for the open source projects like KiCad. Unfortunately they’d removed the free usage feature from personal projects.
I’m using Lazygit and pretty happy with it. Its developer is quite responsive and active.
Agree with @qu1ck - Fossil https://fossil-scm.org/home/doc/trunk/www/index.wiki is very well suited to EDA projects as it provides useful documentation features out of the box.It has a self contained wiki, bug tracking, technotes, and a forum feature built in. A GUI interface is simply ‘fossil ui’. Well worth exploring and simple to install (a single binary). Also ,very well supported by an active and responsive user group.
I also use SVN for assets such as footprints and symbols as file locking is helpful here to avoid merge conflicts.
I’ve used GIT for a few personal projects, mostly to get a better idea of what it is and what it can do, and that is how I got to the point of having a reasonably good idea of what to do to get to a merge request for KiCad.
And although I find GIT a wonderful project, I do not find it very useful for personal projects. Just zipping a project directory (whether uC source or a KiCad project) and backing it up on external media is extremely simple and has 80% of the functionality I want. If I had an always available file server as an extra backup for my git repositories, then GIT may be more useful to me, but copying a zipped backup to such a fileserver may be just as easy.
Final result is that my motivation to learn GIT is very low.
