www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Clarify "Starting as a Contributor" document

reply =?UTF-8?Q?Ali_=c3=87ehreli?= <acehreli yahoo.com> writes:
This page is very good:

   https://wiki.dlang.org/Starting_as_a_Contributor

I need clarifications:

1) Should we change all

   git push -f ...

commands there with

   git push --force-with-lease ...

2) Can you please explain the last sentence of this part:

<quote>
If the pull request is for a bug fix, the commit message should have the 
format "fix issue 1234". This enables the dlang-bot to automatically 
pick up the issue from Bugzilla and post it as a comment on the PR. If 
the PR is already open, then a git rebase is necessary followed by a 
force push. During the rebase, the commit message should be renamed to 
match the one specified.
</quote>

What is "the commit message"? What is "the one specified"?

3) Does Dlang-Bot already do the following or should the contributor do 
it manually?

"Pull request descriptions should contain a hyperlink to the Bugzilla 
issue that is being fixed. This is usually added at the end of the 
description."

Thank you,
Ali
Dec 10 2017
next sibling parent reply Seb <seb wilzba.ch> writes:
On Sunday, 10 December 2017 at 08:18:17 UTC, Ali Çehreli wrote:
 This page is very good:
It's still far from perfect and every improvement for this guide is very welcome.
   https://wiki.dlang.org/Starting_as_a_Contributor

 I need clarifications:

 1) Should we change all

   git push -f ...

 commands there with

   git push --force-with-lease ...
I know that --force is "considered harmful", but so far this has never been an issue and -f should be easier to remember for newbies. tl;dr: I don't have a strong opinion here, but I guess there is no harm done in "officially" recommending -force-with-lease.
 2) Can you please explain the last sentence of this part:

 <quote>
 If the pull request is for a bug fix, the commit message should 
 have the format "fix issue 1234". This enables the dlang-bot to 
 automatically pick up the issue from Bugzilla and post it as a 
 comment on the PR. If the PR is already open, then a git rebase 
 is necessary followed by a force push. During the rebase, the 
 commit message should be renamed to match the one specified.
 </quote>

 What is "the commit message"? What is "the one specified"?
The text is referring to the git commit message. I think the second part is trying to explain the typical scenario that you have opened a PR and forgot to reference a regarding issue in your git commit message. Though git commit --amend is an easier way to edit the last git commit message. The Readme here might also shed some light: https://github.com/dlang-bots/dlang-bot
 3) Does Dlang-Bot already do the following or should the 
 contributor do it manually?

 "Pull request descriptions should contain a hyperlink to the 
 Bugzilla issue that is being fixed. This is usually added at 
 the end of the description."
Yes the bot does this nowadays. This text could be replaced with sth. like: If a pull request isn't a trivial bug, its description should explain the motivation for the change and briefly summarize the changes.
 Thank you,
 Ali
You are very welcome. I hope my answers help. Otherwise don't hesitate to ask again. We really need to improve the contribution experience for newcomers!
Dec 10 2017
parent reply =?UTF-8?Q?Ali_=c3=87ehreli?= <acehreli yahoo.com> writes:
On 12/10/2017 12:36 AM, Seb wrote:

 tl;dr: I don't have a strong opinion here, but I guess there is no harm
 done in "officially" recommending -force-with-lease.
Thanks. I don't care anymore. :)
 2) Can you please explain the last sentence of this part:

 <quote>
 If the pull request is for a bug fix, the commit message should have
 the format "fix issue 1234". This enables the dlang-bot to
 automatically pick up the issue from Bugzilla and post it as a comment
 on the PR. If the PR is already open, then a git rebase is necessary
 followed by a force push. During the rebase, the commit message should
 be renamed to match the one specified.
 </quote>

 What is "the commit message"? What is "the one specified"?
The text is referring to the git commit message. I think the second part is trying to explain the typical scenario that you have opened a PR and forgot to reference a regarding issue in your git commit message.
So, the last sentence should be something like "The rebase allows you an extra opportunity to mention the Bugzilla issue if your original commit did not already mention it."?
 Though
 git commit --amend is an easier way to edit the last git commit message.

 The Readme here might also shed some light:
 https://github.com/dlang-bots/dlang-bot
It was helpful but not for that specific question.
 don't hesitate to ask again.
There is the following part: <quote> First, fork the github repository or repositories you'd like to contribute to (dmd, druntime, phobos etc) by navigating to their respective pages on github.com and clicking "Fork". Then, set up your local git repository to reflect that. For example, consider you want to contribute to phobos and have forked it. Then run these commands: cd ~/code/phobos git remote add myfork https://github.com/username/phobos.git git remote update </quote> That sequence does not work because apparently code/phobos must already be a git repo but the text does not explain where it comes from. So, I added three commands to the sequence and it seemed to work: mkdir -p ~/code/phobos # <-- 1 git init # <-- 2 cd ~/code/phobos git remote add myfork https://github.com/<USERNAME>/phobos.git git remote update git pull myfork master # <-- 3 Was I correct? Of course, it would be better to explain how one gains code/phobos. I think that section should include setting up both the upstream repo and the myfork repo. I think a contributor would regularly be using both. Ali P.S. As I mentioned recently on this newsgroup, the general lack of information on the two repos, "upstream" and "personal fork", were the most detrimental to my understanding of git workflows. We do that in our document but I think setting up "upstream" should be a part of the command sequence above.
Dec 10 2017
parent Seb <seb wilzba.ch> writes:
On Monday, 11 December 2017 at 06:43:46 UTC, Ali Çehreli wrote:
 On 12/10/2017 12:36 AM, Seb wrote:

 [...]
is no harm
 [...]
Thanks. I don't care anymore. :)
 [...]
should have
 [...]
a comment
 [...]
necessary
 [...]
message should
 [...]
second part
 [...]
opened a PR and
 [...]
message. So, the last sentence should be something like "The rebase allows you an extra opportunity to mention the Bugzilla issue if your original commit did not already mention it."?
Yes.
 [...]
commit message.
 [...]
It was helpful but not for that specific question.
 [...]
There is the following part: <quote> First, fork the github repository or repositories you'd like to contribute to (dmd, druntime, phobos etc) by navigating to their respective pages on github.com and clicking "Fork". Then, set up your local git repository to reflect that. For example, consider you want to contribute to phobos and have forked it. Then run these commands: cd ~/code/phobos git remote add myfork https://github.com/username/phobos.git git remote update </quote> That sequence does not work because apparently code/phobos must already be a git repo but the text does not explain where it comes from. So, I added three commands to the sequence and it seemed to work: mkdir -p ~/code/phobos # <-- 1 git init # <-- 2 cd ~/code/phobos git remote add myfork https://github.com/<USERNAME>/phobos.git git remote update git pull myfork master # <-- 3 Was I correct?
Well, the typical behavior is to set your fork as origin and upstream as `upstream`. Also instead of git init etc., you can do a git clone directly.
 Of course, it would be better to explain how one gains 
 code/phobos.
That's what the building from source section should do: https://wiki.dlang.org/Starting_as_a_Contributor#Building_from_source However, I reworked the guide a bit to allow both options.
 I think that section should include setting up both the 
 upstream repo and the myfork repo. I think a contributor would 
 regularly be using both.
Agreed. I tried to improve the contribution guide today. Did my changes help or are you still missing something or isn't fully explained?
 Ali

 P.S. As I mentioned recently on this newsgroup, the general 
 lack of information on the two repos, "upstream" and "personal 
 fork", were the most detrimental to my understanding of git 
 workflows. We do that in our document but I think setting up 
 "upstream" should be a part of the command sequence above.
I added this to the document. Thanks for pointing it out!
Dec 11 2017
prev sibling parent reply Dukc <ajieskola gmail.com> writes:
On Sunday, 10 December 2017 at 08:18:17 UTC, Ali Çehreli wrote:
 This page is very good:

   https://wiki.dlang.org/Starting_as_a_Contributor

 I need clarifications
Another oddity: Someone has apparently made DRuntime build to use ../dmd/generated/windows/32/dmd instead of the "system" dmd recently. Perhaps the idea here is that I do not have to go replacing my system dmd anymore. But the problem is that when I build dmd, for some reason, the build file deletes that generated dmd at the end. Can be resolved by moving the dmd manually to that directory, but that is not explained at the web page. Should we tweak dmd to build into the generated directory instead of working directory, or tweak DRuntime to use ../dmd/src/dmd instead? Or am I missing something?
Dec 11 2017
parent Seb <seb wilzba.ch> writes:
On Monday, 11 December 2017 at 14:13:41 UTC, Dukc wrote:
 On Sunday, 10 December 2017 at 08:18:17 UTC, Ali Çehreli wrote:
 This page is very good:

   https://wiki.dlang.org/Starting_as_a_Contributor

 I need clarifications
Another oddity: Someone has apparently made DRuntime build to use ../dmd/generated/windows/32/dmd instead of the "system" dmd recently. Perhaps the idea here is that I do not have to go replacing my system dmd anymore.
Yes, that someone would be myself. https://github.com/dlang/druntime/pull/1978 It's part of a long-lasting effort to get rid of `src/dmd`, s.t. we can rename the `ddmd` package to `dmd`. See: https://github.com/dlang/dmd/pull/7135
 But the problem is that when I build dmd, for some reason, the 
 build file deletes that generated dmd at the end. Can be 
 resolved by moving the dmd manually to that directory, but that 
 is not explained at the web page. Should we tweak dmd to build 
 into the generated directory instead of working directory, or 
 tweak DRuntime to use ../dmd/src/dmd instead? Or am I missing 
 something?
As explained, it's a huge effort to switch from ../src/dmd to to ../generated, because in the meantime none of the existing CIs and integrations etc. are allowed to break. However, it sounds weird that the generated dmd executable get removed. How do you build dmd and what are your system details?
Dec 11 2017