Update documentation to describe how one can contribute to a package

[doolio]

One of the major strengths for straight.el in my opinion is how easy (or maybe straightforward!) it makes for one to contribute to the development of a package that they use. However, I'm still unsure of the steps one should follow to do so. Say, I wish to contribute to the foo package (and I've not done so before) and which is developed on github, are the following steps correct? Are some unnecessary (maybe some can be combined), missing etc.? Do I need to fork it on github first, update my init.el configuration to point at my fork i.e by changing the receipe? I try to explicit with commands below for clarity.

1. M-x straight-pull-package foo RET or M-x straight-pull-package-and-deps foo RET to ensure one has the latest commit of the foo package
2. M-x dired to ~/.emacs.d/straight/repos/foo
3. M-x magit-status to see the status of the foo respository
4. I hit b c in the magit-status buffer to create a new branch (starting at master, HEAD(?) - I guess they are the same at this point) for the changes one wishes to submit to the foo repo owner for consideration
5. Make all the changes on this new branch

(as an aside I assume if I stay checked out on this new branch straight will rebuild the foo package when I restart Emacs incorporating the changes that I made, if I switch back to the master branch while my PR is being considered straight does not rebuild (nor need to or maybe it does as a precaution as it still detects changes within the repository) the foo package when I restart Emacs?)

6. Now this is where I get confused. On branch master the pushRemote is not set but the upstream is set to origin/master. On my new branch the pushRemote is not set nor does the upstream exist. Should I set the pushRemote or create the upstream branch?

If I hit P p in the magit-status buffer to set the pushRemote the only option is origin which does not belong to me. If I instead hit P u to create the upstream for my branch the options are origin/master (the default) and origin/my-branch. Neither is viable I believe as I (naturally) don't have push privileges to the foo repository (i.e. origin).

I assume it doesn't matter (does it?) if I set pushRemote or create upstream but I guess it makes more sense to create the upstream as fork/master (if I understand #114) to close resemble the settings on the master branch. Do I need to fork foo first on github?

Or does one need to fork foo on github and then update the receipe in their init.el to something like the following before doing anything (assume one already has foo installed)?

(use-package foo
  :straight (:host github : repo "<foo-repo-owner>/foo"
                   :fork (:host github :repo "doolio/foo")))

I think it would help for this to be laid out clearly in the documentation so people learn best practices. I appreciate one could argue this is more a how to use magit request but this may well be related to #65.

I hope I've been clear above. Thanks for your time.

[doolio]

I guess this request should be considered in light of #671.

[raxod502]

I hope I've been clear above.

Indeed, you've been very clear!

Or does one need to fork foo on github and then update the receipe in their init.el to something like the following before doing anything

Yes, this last idea is exactly the intended workflow. And due to somewhat recent work on recipe conciseness and inheritance, you can actually write simply

(use-package foo
  :straight (:fork "doolio"))

and it will default to inheriting all information from the upstream recipe for foo, and configure a fork with the same repo name but owned by you.

You'll also need to run M-x straight-normalize-package on foo after reloading your init-file (or evaluating just that use-package form), so that straight.el will configure the new remote. By the way, the name of this function is terrible and I apologize for coming up with it in the first place.

We certainly need explicit documentation on this, as you're correct that what we have currently doesn't actually cover it.

straight will rebuild the foo package when I restart Emacs incorporating the changes that I made

The package should be rebuilt if and only if any of the files are modified in the repository. Doing Git operations will likely cause a rebuild as well if you're using the filesystem watcher, even if no files in the working directory of the repository are changed. That could be fixed here: https://github.com/raxod502/straight.el/blob/f8783248378a184dfc38e20a6d1aca1dc905a8ff/watcher/straight_watch.py#L50

If I hit P p in the magit-status buffer to set the pushRemote the only option is origin

Yes, as there is only one remote. Once the second remote (named fork) has been created by M-x straight-normalize-package, you can set the pushRemote to it. Personally I actually set pushDefault, which is P C P, then you don't have to do it for every branch.

I guess it makes more sense to create the upstream as fork/master

I would personally recommend setting the upstream to origin/master and pushRemote to fork in Magit, to support a "triangle workflow" as mentioned in https://gist.github.com/anjohnson/8994c95ab2a06f7d2339. You want to pull in changes from the upstream master, but push changes to your fork's feature branch. You don't want to be pushing anything to your fork's master branch.

Let me know if I can clarify anything else.

[doolio]

Firstly, apologies on taking so long to respond. Secondly, thank you for clarifying certain things - it's much clearer now. To make use of the work on recipe conciseness and inheritance I presume the receipe needs to be known to straight in the first place i.e. be defined in one of the receipe repositories otherwise one must provide all the necessary receipe keywords e.g. for a package only available on github.

Personally I actually set pushDefault, which is P C P, then you don't have to do it for every branch. I would personally recommend setting the upstream to origin/master and pushRemote to fork in Magit, to support a "triangle workflow" ... You don't want to be pushing anything to your fork's master branch.

Thank you. This is the kind of best practice approach I was looking for.

[doolio]

You don't want to be pushing anything to your fork's master branch.

Just to be clear on this point. This is only for any changes I may make which should be done on a feature branch. But then later when I pull changes in from the upstream remote origin/master (which may or may not include the changes I submitted for consideration) my fork remote fork/master will be behind and magit will have an unpushed to my fork remote section. I would need to push these changes to my fork remote fork/master if say I run M-x straight-freeze-versions as it seems straight warns you if this is the case.

[raxod502]

To make use of the work on recipe conciseness and inheritance I presume the receipe needs to be known to straight in the first place i.e. be defined in one of the receipe repositories otherwise one must provide all the necessary receipe keywords e.g. for a package only available on github

Yes, that's exactly right.

I would need to push these changes to my fork remote fork/master if say I run M-x straight-freeze-versions as it seems straight warns you if this is the case.

Yes, that's right as well.