should clone user's fork, not main repository

[jmkasunich]

The existing instructions are fine for getting the source and building, but do not comply with the "fork and pull request" method for contributing to the project as described at http://www.machinekit.io/community/contributing/ . The instructions should tell you to open a github account, fork the main repository, and clone your fork. That will allow you to push changes to your fork and generate a pull request. If you follow the instructions on this page you will have to start over before you can contribute.

[luminize]

@jmkasunich there are additional ways to update a cloned fork (from the github portal) for example. One can create a PR from machinekit/machinekit to user/machinekit too. So I guess it depends on what a specific user chooses. I personally always clone the machinekit/machinekit repo, and pull the master branch. But that's my preference. I agree that there needs to be some prerequisite information and additional info in this page. I'll leave this PR open and try to find some time this week to look at this if you're okay with that.

[jmkasunich]

I understand that there are many ways to do things in git. None of them are obvious to git beginners.

http://www.machinekit.io/docs/developing/machinekit-developing/ says to clone the main repository. I found that page first, and followed those directions.

Later I found http://www.machinekit.io/community/contributing/, which says that the machinekit project has selected the "fork and pull request" workflow. Pages linked from there explain the steps, and they are not hard to follow.

But I had already checked out using the first set of instructions. I'm not surprised that it is possible to recover from that situation - git has a million ways to do everything. But as a git newbie I could not figure out how to recover, and especially how to be confident that I was doing it correctly and not simply digging a deeper hole. So once I read the second procedure, I deleted my first checkout and started over. A minor annoyance, about an hour and a half lost time. (Mostly the initial make, I'm doing this on a beaglebone.)

The two machinekit pages mentioned above should be made compatible with each other. If "fork and pull request" is the preferred path for new contributors, then document it. If git experts want to use a different method that is fine for them. But I think you you want contributions (especially to docs) from normal users - people who are unlikely to know anything about git and definitely not git experts. They simply want to be able to fix a doc mistake or omission with minimum pain.

What are the benefits of cloning the main repo as described on the first page, vs cloning your fork as described on the second? Maybe the first procedure makes sense for someone who doesn't want a github account and doesn't plan to contribute changes?

I'm OK with you delaying the pull request, rejecting it, or whatever. It was late last night, otherwise I would have actually updated the step-by-step instructions to support the fork & pull request path.

[dkhughes]

I'm not debating that more documentation would be helpful as I do believe in developer docs that get people up and running really quickly. But, I don't think mass duplication of the git docs here would be prudent with all the excellent git help that is available, including directly on github.

Maybe it would be helpful to have common pitfalls described. Such as, in the situation you describe, you didn't need to recreate the repo since git allows you to have multiple upstream sources. So, in the case where you cloned directly but you wanted to later submit a PR via a fork:

> git clone https://blah.machinekitrepo.imcloning

# N.B.: All of these commands are done in the git repo folder cloned above.
# Okay, I don't have write permission on that repo, but I want to submit my changes
#  without losing my work! By default when you cloned the mk repo, it is labeled 
# "origin". I like to rename it something else, like upstream
> git remote rename origin upstream

# Now, fork on github to an account you have write access to. You have the 
# nonmodified source in your fork, time to add it as your new origin
> git remote add origin http://my.machinekitrepo.fork

# Push your changes to your new fork - assuming your work branch is still 
# the master branch
git push origin master

# Now you can go to your github fork and submit a pull request in the fork and PR work model.

As for the benefits, they are identical in my mind. Both methods can easily get you contributing quickly. If you have no plans to contribute, forking is unnecessary, but a fork does give you a convenient place to keep your code.

Edit: When I get home from work this evening I can work on those doc pages if someone hasn't beaten me to it.

[luminize]

@jmkasunich the main purpose of the "edit me" link was that all cloning and forking should be done by github for you (when we're talking about docs). I think that describing about that (knowing what happens) could be a bit more in-depth, especially for the first time user. But the need for git-fu should not be needed at all. Especially not the casual user who will find a typo. FWIW I'm not a git-guru, and I struggled myself with git a lot to get going.

@dkhughes a common pitfalls section is a good idea. Especially when one starts with developing. It's better to find good explanation like you say on github / other about a subject instead and linking to it (in a new browser tab preferably)

[jmkasunich]

@luminize Understood that "edit me" is for docs. It does eliminate the need for git-fu. Not quite a newb friendly as say editing Wikipedia, but not bad. A few minor tweaks would make it even better. But this pull request is about making contributions to the source.

@dkhughes You just explained to me how to recover from my mistake. I appreciate that, but what I really want to do is help people avoid my mistake.

I agree with both of you that linking to a good explanation is as good or better than duplicating the explanation. I found the explanation at https://help.github.com/articles/fork-a-repo/ to be very helpful. In fact I think I understand dkhughes's recover process better in that context - the goal is to make the output of git-remote -v be correct. I did it by the process on the Fork-a-Repo page, so that origin was my fork and upstream was machinekit/machinekit. If I understand your recovery process, you started with origin as machinekit/machinekit, then you changed origin to upstream, and added a new origin pointing at your fork. Same end result, different path. (important note - WITH the git-remote -v output I started to understand things. Without it, your recovery process was a black box process that I could execute but not understand.)

Getting back to the matter of helping people avoid my mistake:

Specifically, there are two different flows being recommended on two different pages:

1) http://www.machinekit.io/docs/developing/machinekit-developing/ 2) http://www.machinekit.io/community/contributing/

I originally found those pages via google. Navigating to them from the machinekit homepage has been illuminating.

From the home page, you get to (1) by clicking Documentation, Developer Manual, Setting Up Development Environment, General Development Setup & Packages You get to (2) by clicking Community, Contributing

Maybe those two destination pages simply need to be merged?

(1) has much very good detail that is missing from (2) - for example, I didn't know that you need to uninstall the packaged version of machinekit before building from source. Also, info about arguments passed to ./configure, package info, check-system-configuration, etc.

(2) has a lot of philosophy and policy stuff, but the meat (for me at least) is the "setting up to contribute" section, which promotes the fork & pull request workflow. It uses links to github pages rather than walking through things like forking in detail.

My thought is that (2) should keep the philosophy stuff but the "setting up" section should point to (1). And (1) should be changed to support the fork & pull request model, and add the git config info currently in (2). (1) could/should use the "create a fork" github link from (2) instead of duplicating things.

Is there a particular reason that (1) recommends cloning machinekit/machinekit instead of the user's fork? (assuming the intended audience is people who don't know enough to have their own preferred workflow).

[dkhughes]

@jmkasunich

Is there a particular reason that (1) recommends cloning machinekit/machinekit instead of the user's fork? (assuming the intended audience is people who don't know enough to have their own preferred workflow).

This is what I was trying to drive at (poorly) with my initial response. I wasn't trying to only explain how to correct your (not-a-)mistake, I simply used your experience as an example of a possible FAQ we could add to the documents. I think the biggest mind shift someone who is new to git from say, subversion, needs to make is that the clone procedures you are describing are really equivalent. What I mean by that is if you want to keep your fork in sync with the master repo, you have two choices:

1. Delete and refork every time upstream has a change you want
2. Add the master repository as a remote source and fetch/pull from it.

See why I don't consider what you did a mistake? Bullet 2 can be achieved by either directly cloning your fork and adding upstream, or cloning the master repo and adding your fork. Tom-ay-to, Tom-ah-to. I agree that we should definitely document those choices as a git primer for machinekit, with the example being more detailed (i.e., including remote -v, etc.) than my quick response from earlier.

I defer to the more experienced guys about merging your (1) and (2) links. I've always viewed the two pages as (1) "How to build machinekit from source", maybe because you want to hack in it a little, and (2) as developer's responsibilities to ensure machinekit ecosystem is maintainable and grows. If we get a little consensus or opinions from the more senior folks I will help out as much as I can updating the pages.

[luminize]

There's nothing better than an example, how about we use asciinema for this? Showing snippets/examples?

[jmkasunich]

if you want to keep your fork in sync with the master repo, you have two choices:

1. Delete and refork every time upstream has a change you want
2. Add the master repository as a remote source and fetch/pull from it.

Choice 1 seems painful. I now understand that we both got to choice 2 using two different methods.

At this point I agree that (1) should be "how to build from source" as you say. And (1) would continue to instruct the person to clone from machinekit/machinekit - that has the advantage of not requiring a github account (I think?).

Somewhere at the end of (1), there should be a note saying "If you would like to contribute your changes back to the project, please go to (2)".

At (2), it would say "if you do not already have a working copy, see (1). Once you have a working copy, set up for contribution as follows:" followed by steps (or links to good explanations) for opening a github account, making a personal fork, and using your process to set up the personal fork as origin and machinekit/machinekit as upstream. A link to https://help.github.com/articles/syncing-a-fork/ could explain how to keep the personal fork in sync with upstream, and so on thru creating and submitting a pull request.

In any case, I think my -docs pull request that revises (1) and started this thread needs to be canceled. We are converging on a better edit than the one I proposed last night.

[jmkasunich]

@luminize Regarding an example - (1) (http://www.machinekit.io/docs/developing/machinekit-developing/) is a perfectly good detailed step-by-step process. Worked great. I now understand that I could have gotten from the end of (1) to where I needed to be without starting over, so my initial suggested change at the beginning of (1) is not required. Instead, I'd like to add something to the end of (1) pointing potential contributors to (2) (http://www.machinekit.io/community/contributing/) and instructions at (2) to get them the rest of the way from "build from source" which (1) accomplishes to "contribute via pull request"

[dkhughes]

@luminize How cool is asciinema!? That almost makes writing docs enjoyable, heh. Also, should we move this to an issue to track instead of a PR? Or, is there an existing issue we should work from?

@jmkasunich

machinekit/machinekit - that has the advantage of not requiring a github account (I think?).

Correct, anonymous pulls are allowed which is a bonus if the person doesn't have a github account.

[jmkasunich]

Please tell me that asciinema works with ancient browsers and slow machines.

Personally I'm not a fan of animations. The pace is either too fast (pause can help) or too slow (frustrating).

And if the documentation is ONLY the recorded commands and resulting output I don't learn anything. The important part of the documentation is the text between the commands that explains what the commands are doing and why each one matters.

For example, under "Get and build the source" at http://www.machinekit.io/docs/developing/machinekit-developing/, the comments above "debian/configure -prx" and "./configure" are FAR more important than the commands themselves. They contain information that is unique to the machinekit project and difficult to find otherwise.

Another example: https://help.github.com/articles/fork-a-repo/#step-3-configure-git-to-sync-your-fork-with-the-original-spoon-knife-repository The words are as important if not more important than the commands.

[mhaberler]

We have made the decision to prioritize web over non-web, see the tracker how we arrived there. That is bad news for the determined console user (singular so far) if there is no browser in sight. But since you are evidently using the github website, it looks like you have a more than adaequately powered browser.

If one wants to fix a typo, the 'Edit this page' button is enough. Add a page: add new file in the browser right in github. Delete some legacy stuff which never worked anyway: hit delete file. That covers the drive-by actions.

I do not think teaching git or github basics is in scope. Let me be blunt: this are expected basic skills - 'IT', 'no git' and 'github not spoken' equals 'not employable' anyway these days (applies even to my nephew: lawyer with an IT habit).

Scope is essential - for instance I have zero interest of providing unending Linux bootcamps for the let-me-graduate-from-8-bit-embedded-oh-there's-an-operating-system crowd. Noble cause, not doable given resources and goals, so not in scope. No forum, no docs, need to man up without us.

As for the necessity to 'build on target': probably the only people with a credible justification to compile some non-comp files and debug on target over the last couple of years were @cdsteinkuehler (PRU stuff) @the-snowwhite (mksocfpga), @zultron and me (drivers and OS stuff), plus the occasional drive-by contributors. The other 99+% of the job can perfectly be done elsewhere.

Some people have kept that habit stemming from kthreads days where that was needed thanks to lack of userland/kernel separation, but professionally proposing that approach might be a career changer in the embedded industry as well; nevermind the waiting pains.

Maybe it also helps to frame things not in terms of wrong or right but rather different. If you want to help on these terms, you are very welcome!

[cdsteinkuehler]

On 8/8/2016 6:28 PM, Michael Haberler wrote:

We have made the decision to prioritize web over non-web, see the tracker how we arrived there. That is bad news for the determined console user (singular so far) if there is no browser in sight. But since you are evidently using the github website, it looks like you have a more than adaequately powered browser.

I don't disagree with the decision to prioritize web/asciidoc and deprecate man pages, but I also understand John's point about missing man pages being a poor user experience.

What about crafting a stub man page that can point people to the mank command, the online docs, and maybe recommend adding the --help switch? Just like all those "official" *nix man pages that say "see the texinfo documentation for full details". :)

Charles Steinkuehler charles@steinkuehler.net

[ArcEye]

What about crafting a stub man page that can point people to the mank command, the online docs, and maybe recommend adding the --help switch? Just like all those "official" *nix man pages that say "see the texinfo documentation for full details". :)

That would mean 223 stub files at current figures, so as not to second guess what the user might look up. Well 222 symlinks and one actual file to be exact .

In fact I like it so much I have begun to implement it :+1: https://github.com/machinekit/machinekit-docs/pull/220#issue-170125673

There is now a -h switch to mank, or is that not what you meant?

[cdsteinkuehler]

On 8/9/2016 5:01 AM, ArcEye wrote:

There is now a |-h| switch to mank, or is that not what you meant?

I meant the stub man page should suggest running the command (eg: halcmd, halshow, etc) with a -h or --help switch (looks like most of the commands only support short options, so -h).

Charles Steinkuehler charles@steinkuehler.net

[ArcEye]

Ah I see.

I'll add that to the stub.

[ArcEye]

Now working, just need a couple of changes to get merged and will finish it tomorrow.

I am no longer a fan of ruby (if I ever was). It's file handling routines within fpm (used for packaging in Jenkins) pass straight over symlinks and will not include them in a package.

Caused me all sorts of problems until I figured out what was happening.

[jmkasunich]

Closing this PR. My initial commit was definitely not the right solution to the problem.