developer.jelix.org is not used any more and exists only for history. Post new tickets on the Github account.
developer.jelix.org n'est plus utilisée, et existe uniquement pour son historique. Postez les nouveaux tickets sur le compte github.

Changes between Version 4 and Version 5 of en/patches


Ignore:
Timestamp:
Aug 17, 2010, 10:39:20 AM (10 years ago)
Author:
laurentj
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • en/patches

    v4 v5  
    2121== Creating the patch ==
    2222
    23 In the directory of your local copy of the repository, you should have made all your changes. Go into the trunk directory and type:
     23There are 3 ways to provide patch, depending of how you work and how you contribute.
     24
     25=== You create occasionnaly a patch ===
     26
     27The simplier way is to use "hg diff". In the directory of your local copy of the repository, you should have made all your changes. When your changes are ok, just type:
    2428
    2529  hg diff > mypatch.diff
    2630
    27 Then you have a mypatch.diff file.
     31Then you have a mypatch.diff file. Perhaps you should made same changes in other branches. Provide then a patch for these branches.
    2832
    29 Perhaps you should made same changes in other branches. Provide then a patch for these branches
     33Submit the patch into a ticket on developer.jelix.org. The ticket can be an existant one, or perhaps you have to create it. Create/edit the ticket and attached the file. Then you have to request a review. See below.
    3034
    31 == Proposing the patch ==
    3235
    33 Submit it into a ticket on developer.jelix.org. The ticket can be an existant one, or perhaps you have to create it. Create/edit the ticket and attached the file.
    3436
    35 If your patch is not finished (because you haven't no more time to work on it for example), so add a comment to explain the situation, and then this is the end for you.
     37=== You are an active contributor ===
     38
     39If you provide often some patches (unrelated or not), the best way is to manage a queue of patch, with the "mq" extension of Mercurial. Having his own branch/fork of the repository for that is not recommended, as a reviewer can refused your commit. So you can have at the end several commit for a single "patch", and the problem is that we want to have a clear history (one commit per ticket, except for big changes).
     40
     41You can host your queue only on your computer, or you can share your queue on bitbucket. If you don't use bitbucket, just attach your patches on corresponding tickets and then request a review (see below).
     42
     43If you want to share your queue of patchs (and it can be useful for reviewer to see the history of changes on your patch, review after review), you can use bitbucket. Create an account on bitbucket.org, and follow this instructions (replace "jelix-trunk" by jelix-1.1.x or other branch name if you want to work with branches):
     44
     45  * Go on http://bitbucket.org/jelix/jelix-trunk/
     46  * click on "patch queue", fill the form, by giving a name to your repository for the queue. Take "jelix-trunk-patches" for example
     47  * you can then clone your new repository which contains the patch (use qclone, and not clone !):
     48{{{
     49hg qclone ssh://hg@bitbucket.org/your-login/jelix-trunk-patches
     50}}}
     51  * On your computer, you have now a jelix-trunk-patches directory, with a .hg/patches/ directory. Now fill the directory with the content of jelix-trunk, to have source code of jelix with your patchs queue
     52{{{
     53cd jelix-trunk-patches
     54hg pull -u ssh://hg@bitbucket.org/jelix/jelix-trunk
     55}}}
     56
     57You can start now to work. Let's create a first patch:
     58{{{
     59# create the patch
     60hg qnew ticket123.patch
     61
     62# do some modifications on files
     63...
     64# refresh the patch each time you made some modifications
     65hg qrefresh
     66
     67# you can then commit modification '''in the patch queue''', not in the repository it self
     68hg qcommit -m "my first work on the patch for ticket 123"
     69}}}
     70
     71You can repeat qrefresh, qcommit to improve your patch. You can create several patch with qnew. Remember that changes you make are for the last patch. If you want to change an older patch, you have to use qpop to remove top patchs. To apply again newer patch, use qpush.
     72
     73Read [http://hgbook.red-bean.com/read/managing-change-with-mercurial-queues.html the tutorial on queues] to know more on queues.
     74
     75Each time you want to update source code of jelix, do
     76{{{
     77hg qpop -a  # remove your patches from the source code
     78hg pull -u ssh://hg@bitbucket.org/jelix/jelix-trunk
     79hg qpush -a
     80}}}
     81
     82If conflicts are detected during hg qpush, fix conflicts (don't forget to do hg qrefresh) and restart qpush until it is ok.
     83
     84To publish your patches on bitbucket, go into the directory .hg/patches and:
     85{{{
     86hg push
     87}}}
     88
     89When one of your patch is ready, go on the corresponding ticket on developer.jelix.org and ask a review, by indicating the URL of your queue repository on bitbucket and the name of the patch. See below to request a review.
     90
     91When one of your patch is integrated in the official repository, delete it from your queue before updating the source code of jelix
     92{{{
     93hg qpop -a
     94hg qdelete ticket123.patch
     95hg qcommit -m "remove ticket123.patch"
     96cd .hg/patches/
     97hg push
     98cd ../..
     99hg pull -u ssh://hg@bitbucket.org/jelix/jelix-trunk
     100hg qpush -a
     101}}}
     102
     103=== You want to propose some patches for a big change ===
     104
     105Maintening a queue of patch can be tiring when you work on a big change (integration of a new big component for example). The best way in this case is to have your own branch, with your own commits, and this branch will be merge with the trunk at the end.
     106
     107Bitbucket allow you to publish a clone of a repository, and to commit changes to it. Then you can use the feature "pull request" of bitbucket to inform the owner of the "official" repository, to integrate your commit into his repository.
     108
     109So you can "fork" a jelix repository, commit into your clone, and request a pull. Add a comment on the corresponding ticket on developer.jelix.org to inform other contributors that you've made some changes.
     110
     111Try to commit clear step, in order to have an understandable history. Each changeset should correspond to a specific step of the change. Don't hesitate to use the mq extension of Mercurial to track your changes before committing them into your clone on bitbucket. And of course, [wiki:en/commit your messages of changset should be well formatted].
     112
     113
     114== Requesting a review ==
     115
     116If your patch is not finished (because you haven't no more time to work on it for example), so add a comment on the corresponding ticket to explain the situation, and then this is the end for you.
    36117
    37118But if it is a finished patch, you should ask a review by setting the "review" field of the ticket to "review?". Then a reviewer will verify your patch. If it is ok, he will set "review+". If your patch needs some improvements, he will  set "review-" and then you will have to make improvements he asked and you will create a new patch, submit it on the ticket, ask "review?" and so on.
     
    41122See [wiki:en/commit to know the 'commit styles'].
    42123
    43 = Using Bitbucket and pull requesting =
    44124
    45 An other way to provide a patch, is to work on bitbucket.org. Sources of Jelix are stored on Bitbucket.org. If you are registered on this site, Bitbucket allow you to publish a clone of a repository, and to commit changes to it. Then you can use the feature "pull request" of bitbucket to inform the owner of the "official" repository, to integrate your commit into his repository.
    46 
    47 So you can "fork" a jelix repository, commit into your clone, and request a pull. Add a comment on the corresponding ticket on developer.jelix.org to inform other contributors that you've made some changes.
    48 
    49 Please don't propose tens of changesets/commits for a same ticket. Your clone should have only one commit, except if it is a big change. In this commit, each changeset should correspond to a specific step of the change. Don't hesitate to use the mq extension of Mercurial to track your changes before committing them into your clone on bitbucket. And of course, [wiki:en/commit your messages of changset should be well formatted].
    50125
    51126----