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 5 and Version 6 of en/patches


Ignore:
Timestamp:
Aug 20, 2011, 10:44:37 AM (9 years ago)
Author:
laurentj
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • en/patches

    v5 v6  
    33You have to follow this steps, in order to create a patch.
    44
    5  1. retrieve the last version of jelix (trunk) from the repository (and not from the download area !)
     5 1. retrieve the last version of jelix from the repository (and not from the download area !)
    66 1. create the ini file for the build script
    77 1. modify the sources of jelix in order to fix the bug you want to correct, or to made improvements
     
    99 1. test your changes and launch unit tests in the testapp application
    1010 1. if not ok, back to the third step.
    11  1. all is ok, you can create the patch.
     11 1. all is ok, you can create the patch or commit in your clone on github.
    1212
    1313
     
    2525=== You create occasionnaly a patch ===
    2626
    27 The 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:
     27The simplier way is to use "git 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:
    2828
    29   hg diff > mypatch.diff
     29  git diff > mypatch.diff
    3030
    31 Then you have a mypatch.diff file. Perhaps you should made same changes in other branches. Provide then a patch for these branches.
     31Then you have a mypatch.diff file.
    3232
    33 Submit 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.
     33If your modification has to be applied on stable branches, create the patch with the oldest branch.
     34
     35Submit the patch into a ticket on developer.jelix.org. The ticket can be an existing one, or perhaps you have to create it. Create/edit the ticket and attached the file. Then you have to request a review.  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. When you have "review+", you can commit the patch in the repository if you have write acces, or a "commiter" will do it for you.
     36
     37=== You are an active contributor ===
     38
     39If you provide often some patches (unrelated or not), or if you'are familiar with Git, the best way is to "fork" on Github.com. Please create a branch for each modification you want to provide, so we could merge them independently, after the review. As we would like to have a "clear" history, for little modifications, try to create only one commit, not 10 or 20 :-). For complex modifications, it's better of course to have several commit. Try to commit clear steps, in order to have an understandable history. Each changeset should correspond to a specific step of the change.
     40
     41When your modification is done, push your changes on your github account, and do a "pull request" on github.
    3442
    3543
    3644
    37 === You are an active contributor ===
    3845
    39 If 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).
     46== Guide lines for commit ==
    4047
    41 You 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).
     48Here are some rules to follow for commit.
    4249
    43 If 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):
     50=== Conditions ===
    4451
    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 !):
     52For contributors having rights access on the repository, they can commit and push directly on the official repository, reviewed patchs and minor modifications (syntax errors, mispelling...).
     53
     54Every patchs/pull request should be reviewed, before their landing on the official repository.
     55
     56Of course, changes should not break something: tests should be ok (or adapted to be ok).
     57
     58Every changes should contain tests if possible.
     59
     60=== Commit message ===
     61
     62The message of a commit:
     63
     64 * should be written in english
     65 * it should contain:
     66    - the "ticket #xxx" where xxx is the number of a ticket on developer.jelix.org.
     67    - the description of the change
     68    - the reviewer name: "r=bob"
     69 * you must indicate the author of the patch with the -u option if you're not the author
     70
     71Example:
    4872{{{
    49 hg qclone ssh://hg@bitbucket.org/your-login/jelix-trunk-patches
     73git commit -u "Bob <bob@example.local>" -m "ticket #68987: added support of multiline tags in templates. r=laurent"
    5074}}}
    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 {{{
    53 cd jelix-trunk-patches
    54 hg pull -u ssh://hg@bitbucket.org/jelix/jelix-trunk
    55 }}}
    56 
    57 You can start now to work. Let's create a first patch:
    58 {{{
    59 # create the patch
    60 hg qnew ticket123.patch
    61 
    62 # do some modifications on files
    63 ...
    64 # refresh the patch each time you made some modifications
    65 hg qrefresh
    66 
    67 # you can then commit modification '''in the patch queue''', not in the repository it self
    68 hg qcommit -m "my first work on the patch for ticket 123"
    69 }}}
    70 
    71 You 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 
    73 Read [http://hgbook.red-bean.com/read/managing-change-with-mercurial-queues.html the tutorial on queues] to know more on queues.
    74 
    75 Each time you want to update source code of jelix, do
    76 {{{
    77 hg qpop -a  # remove your patches from the source code
    78 hg pull -u ssh://hg@bitbucket.org/jelix/jelix-trunk
    79 hg qpush -a
    80 }}}
    81 
    82 If conflicts are detected during hg qpush, fix conflicts (don't forget to do hg qrefresh) and restart qpush until it is ok.
    83 
    84 To publish your patches on bitbucket, go into the directory .hg/patches and:
    85 {{{
    86 hg push
    87 }}}
    88 
    89 When 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 
    91 When one of your patch is integrated in the official repository, delete it from your queue before updating the source code of jelix
    92 {{{
    93 hg qpop -a
    94 hg qdelete ticket123.patch
    95 hg qcommit -m "remove ticket123.patch"
    96 cd .hg/patches/
    97 hg push
    98 cd ../..
    99 hg pull -u ssh://hg@bitbucket.org/jelix/jelix-trunk
    100 hg qpush -a
    101 }}}
    102 
    103 === You want to propose some patches for a big change ===
    104 
    105 Maintening 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 
    107 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.
    108 
    109 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.
    110 
    111 Try 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 
    116 If 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.
    117 
    118 But 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.
    119 
    120 When you have "review+", you can commit the patch in the repository if you have write acces, or a "commiter" will do it for you.
    121 
    122 See [wiki:en/commit to know the 'commit styles'].
    123 
    124 
    12575
    12676----