1,848
edits
(Advertise GUI for newbies.) |
|||
(9 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
[https://www.mercurial-scm.org Mercurial] (sometimes referred to as {{codeline|hg}}) is the source code management system used for Octave development. | [https://www.mercurial-scm.org Mercurial] (sometimes referred to as {{codeline|hg}}) is the source code management system used for Octave development. | ||
Everybody is free to '''run, copy, distribute, study, change and improve'''<ref>https://www.gnu.org/philosophy/free-sw.en.html</ref> Octave's source code, given in the main repository at https://www.octave.org/hg/octave. Use Mercurial to get the latest version of Octave <pre>hg clone https://www.octave.org/hg/octave</pre> | |||
{{Note|[https://tortoisehg.bitbucket.io/ TortoiseHg] is a GUI for Mercurial and it is especially recommended for users doing their first steps with source code management systems. Linux, macOS, and MS Windows are supported.}} | {{Note|[https://tortoisehg.bitbucket.io/ TortoiseHg] is a GUI for Mercurial and it is especially recommended for users doing their first steps with source code management systems. Linux, macOS, and MS Windows are supported.}} | ||
Line 5: | Line 7: | ||
== Creating and submitting patches (changesets) == | == Creating and submitting patches (changesets) == | ||
If you want to share your modifications, for example to fix a nasty '''bug #42424''', you cannot just submit your changes to Octave's main repository. You have to generate a '''patch (or changeset)''' so other Octave developers can include them into Octave's source code. | |||
# Get the latest | # Get the latest version of Octave (or some Octave package) <pre>hg clone https://www.octave.org/hg/octave</pre> or when already cloned <pre>hg pull && hg update</pre> | ||
# Make your changes (fix bug #42424) and save them. '''Make sure that your changes don't introduce new bugs!''' Thus it is recommended to [[Building | build Octave]] and to [[Tests | run Octave's test suite]] before proceeding.<br>{{Warning|Please follow the [[Contribution guidelines]] for C/C++ or Octave code files!}} | # Make your changes (fix bug #42424) and save them. '''Make sure that your changes don't introduce new bugs!''' Thus it is recommended to [[Building | build Octave]] and to [[Tests | run Octave's test suite]] before proceeding.<br>{{Warning|Please follow the [[Contribution guidelines]] for C/C++ or Octave code files!}} | ||
# Commit your changes <pre>hg commit</pre> Mercurial will open your default editor<ref>To set your default Mercurial editor, read https://www.mercurial-scm.org/wiki/editor .</ref> and ask you for a commit message. Please follow the [[commit message guidelines]], e.g. <syntaxhighlight lang="text">help.m: Display relevant topics first (bug #42424) | # Commit your changes <pre>hg commit</pre> Mercurial will open your default editor<ref>To set your default Mercurial editor, read https://www.mercurial-scm.org/wiki/editor .</ref> and ask you for a commit message. Please follow the [[commit message guidelines]], e.g. <syntaxhighlight lang="text">help.m: Display relevant topics first (bug #42424) | ||
Line 66: | Line 68: | ||
<syntaxhighlight lang="bash"> | <syntaxhighlight lang="bash"> | ||
hg pull https://www.octave.org/hg/octave | hg pull https://www.octave.org/hg/octave # Get latest remote "tip" | ||
hg update -r my-gsoc | hg update -r my-gsoc # Activate bookmark "my-gsoc" | ||
hg merge | hg merge tip # Merge "tip" into "my-gsoc" | ||
hg commit -m "maint: merge default to my-gsoc" | hg commit -m "maint: merge default to my-gsoc" | ||
hg push ssh://student@public.server.org/octave | hg push ssh://student@public.server.org/octave | ||
Line 75: | Line 77: | ||
=== Preparing for code reviews === | === Preparing for code reviews === | ||
At the time of the mid-term or final review (or whenever the mentor requires it) students should prepare their code | At the time of the mid-term or final review (or whenever the mentor requires it) students should prepare their code for review and possibly inclusion into the main repository. | ||
for review and possibly inclusion into the main | |||
# Create a full log of changes <pre>hg log --template=changelog --no-merges --user student-name</pre> If students have been following the [[Commit message guidelines]] the output is a good starting point for the commit message in the next step. Some manual post-processing might be necessary: | |||
#* Each touched file should appear only once. | |||
#* Do not mention backed-out commits. | |||
# Prepare a singe patch (changeset) including all code that should be submitted for review <syntaxhighlight lang="bash"> | |||
hg pull https://www.octave.org/hg/octave # Get remote "tip" and "@" | |||
hg update -r @ # Activate bookmark "@" | |||
hg merge my-gsoc # Merge "my-gsoc" into "@" | |||
hg commit | |||
hg export -r tip -o mid-term-review.patch | |||
</syntaxhighlight> The file {{Path|mid-term-review.patch}} can uploaded to the [https://savannah.gnu.org/patch/?group=octave patch tracker]. <br/> Finally, there is a subtle difference between <code>"tip"</code>, which is a reference to the (local or remote) changeset added to the repository most recently and the bookmark <code>"@"</code> used by the Octave developers to point to the latest remote changeset. Often both refer to the very same changeset and they can used interchangeably. | |||
</ | |||
== Example Mercurial configuration == | == Example Mercurial configuration == |