1,847
edits
mNo edit summary |
(→Mercurial configuration: Add missing color "gray". Minor changes of spelling and whitespace.) |
||
(11 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
[[wikipedia:Mercurial|Mercurial]] (sometimes referred to as {{codeline|hg}}) is the | [[wikipedia:Mercurial|Mercurial]] (sometimes referred to as {{codeline|hg}}) | ||
is the source code management system currently used to develop | |||
Octave. | |||
== Introduction to Mercurial == | |||
An introduction to Mercurial is completely outside the scope of this document. | |||
There are plenty of available documentation on the topic. Some recommendations | |||
are: | |||
* [http://hginit.com/ Hg Init] | |||
* [https://www.mercurial-scm.org/wiki/Tutorial Mercurial tutorial] | |||
* [https://www.mercurial-scm.org/wiki/QuickStart Mercurial quick start] | |||
== Contributing to Octave == | |||
The preferred method to contribute to Octave is with Mercurial changesets. | |||
Other forms of contributions (e.g., simple diff patches) are | |||
also acceptable, but they slow down the review process. | |||
If you plan on contributing to Octave: | |||
* See other [[Contribution guidelines]] | |||
* Always include commit messages in changesets. Please follow the Octave [[commit message guidelines]] | |||
* Follow the style guides for both [[Octave style guide|Octave]] and [[C++ style guide|C++]] languages. | |||
== Getting the development sources == | |||
To clone the Octave repository: | |||
hg clone http://www.octave.org/hg/octave octave | |||
Octave packages like image, signal, control, etc. are not parts of Octave | |||
itself, they belong to the Octave Forge. Each package has its own | |||
repository, a list of which can be found | |||
[http://sourceforge.net/p/octave/_list/hg?source=navbar here]. | |||
You can clone them in a similar way, for example, to clone the signal package | |||
hg clone http://hg.code.sf.net/p/octave/signal octave-signal | |||
== Mercurial configuration == | |||
You can use the following to start your hgrc | |||
{{File||<pre> | |||
[ui] | |||
username = Your Name <your@email> | |||
[extensions] | |||
color = | |||
histedit = | |||
pager = | |||
rebase = | |||
strip = | |||
[pager] | |||
pager = LESS='FSRX' less | |||
attend = help, annotate, cat, diff, export, glog, log, outgoing, incoming | |||
[diff] | |||
showfunc = True | |||
[color] | |||
mode = terminfo | |||
## Custom colors | |||
color.gray = 244 | |||
color.orange = 202 | |||
color.lightyellow = 191 | |||
color.darkorange = 220 | |||
color.brightyellow = 226 | |||
status.modified = magenta bold | |||
status.added = green bold | |||
status.removed = red bold | |||
status.deleted = cyan bold | |||
status.unknown = gray bold | |||
status.ignored = gray bold | |||
## Colours for each label | |||
log.branch = cyan | |||
log.summary = lightyellow | |||
log.description = lightyellow | |||
log.bookmark = green | |||
log.tag = darkorange | |||
log.graph = blue | |||
## Colors for each phase | |||
changeset.secret = blue bold | |||
changeset.draft = red bold | |||
changeset.public = orange | |||
desc.here = bold blue_background | |||
[bookmarks] | |||
track.current = True | |||
[alias] | |||
glog = log --graph | |||
top = log --graph -l | |||
</pre>}} | |||
== Submitting patches == | == Submitting patches == | ||
When you do not have push permissions to the repository (you cannot add your changes using mercurial itself) and you have a modification to the current GNU Octave code, you have to generate a patch (or changeset) so developers with permissions can include them in the code. The overview of the process is as follows | When you do not have push permissions to the repository (you cannot add your changes using mercurial itself) and you have a modification to the current GNU Octave code, you have to generate a patch (or changeset) so developers with permissions can include them in the code. The overview of the process is as follows | ||
# Change the code and test that your changes do work (write tests, that's the best!). | # Change the code and test that your changes do work (write tests, that's the best!). | ||
Line 8: | Line 108: | ||
# Post your patch in the [https://savannah.gnu.org/patch/?group=octave Patch tracker]. | # Post your patch in the [https://savannah.gnu.org/patch/?group=octave Patch tracker]. | ||
Patch submissions is done via the [https://savannah.gnu.org/bugs/?group=octave bug] | |||
or [https://savannah.gnu.org/patch/?group=octave patch] trackers. Either | |||
way, you can submit via two different methods: pull requests on attaching | |||
a changeset file. | |||
=== Pull request === | |||
=== Creating changesets with hg === | This is the cleaner way. You push your clone to public site, and ask on the | ||
bug tracker to pull a specific changeset from it. It makes special sense if | |||
you plan to send more patches in the future but requires to host the clone | |||
somewhere. Free mercurial repositories are available on [https://bitbucket.org/ bitbucket] | |||
=== Creating changesets files with hg === | |||
==== Simple way ==== | ==== Simple way ==== | ||
* Update to the latest revision. | * Update to the latest revision. | ||
Line 47: | Line 132: | ||
<pre> hg export -r tip -o mypatch.patch </pre> | <pre> hg export -r tip -o mypatch.patch </pre> | ||
* Save the output to a file and upload it to the patch tracker. If your patch file is larger than the upload limit, you can compress it before uploading. Please use a free format! | * Save the output to a file and upload it to the patch tracker. If your patch file is larger than the upload limit, you can compress it before uploading. Please use a free format! | ||
== Mercurial Tips for SoC students == | == Mercurial Tips for SoC students == | ||
Line 137: | Line 202: | ||
<code>hg commit </code><br/> | <code>hg commit </code><br/> | ||
<code>hg export @ > mid-term-review.changeset </code><br/> | <code>hg export @ > mid-term-review.changeset </code><br/> | ||
the file mid-term-review.changeset can then be sent to the | the file mid-term-review.changeset can then be sent to the [mailto:octave-maintainers@octave.org mailing list] or posted | ||
to the [ | to the [https://savannah.gnu.org/patch/?group=octave patch tracker]</li> | ||
</ol> </li> | </ol> </li> | ||
</ol> | </ol> | ||
Line 144: | Line 209: | ||
== Mercurial Tips for SoC mentors == | == Mercurial Tips for SoC mentors == | ||
Will fill in this section after trying out the above procedure at least once with a student | Will fill in this section after trying out the above procedure at least once with a student and actually pushing his changes to the main repo. | ||
and actually pushing his changes to the main repo. | |||
<!--- | <!--- | ||
<code> | <code> | ||
Line 171: | Line 234: | ||
==External links== | ==External links== | ||
* [ | * [https://www.mercurial-scm.org/ Official website] | ||
[[Category:Development]] | [[Category:Development]] |