Contributing changesets

— Jan Decaluwe 2008/07/25 06:21

The MyHDL Source code repository can be used for several things, such as browsing through the development history, and tracking development. In addition, you can use it to contribute your own changesets to the tool. The repository is set up so that every contributed change is reviewed and applied or rejected by me. Therefore, your goal as a contributor should be to minimize my work What is needed is the following:

• I need to understand why the change is needed, and why it will be useful to many people
• I need some confidence that it won't break current and foreseeable things
• the changes have to be tested
• you have to use mercurial to manage the patches

The implementation of these requirements is described in more detail in the following sections.

Don't send me patches out of the blue.

Your first step is to communicate about the problem or feature with the MyHDL community. Start a discussion in the Mailing List and Newsgroup or (if you are certain) add an entry in the Bug Tracker.

The result will be a fruitful discussion that hopefully results in a decision about what should be done. The byproduct will be a specification for the work.

To manage your patches, use mercurial. By doing so, I can simply use my normal development workflow to incorporate your work. Moreover, your name will be preserved as the author, so you get the credit you deserve.

In mercurial terminology, a set of patches that belong together is called a changeset. Assuming you know how to work with the Source code repository, creating changesets is easy. You make changes in your local repository clone, and use:

$ hg commit

to create a new changeset that contains your patches.

At a certain point you will want to publish your changesets, so that everyone can benefit from them. However, don't publish your work until it is complete. Make sure there are no loose ends that others will have to address after you. Most importantly, make sure your changes have been tested.

Run the MyHDL regression tests to make sure nothing breaks. As a minimum, the tests in test/core should be run. If your changes are related to conversion to VHDL/Verilog, the test in the test/conversion directories should be run also.

Presumably, you have some test for your changes in place. If at all possible, turn it into a test that can be added to the regression test suites.

You may need a number of changesets to complete your work. That isn't a problem at all, on the contrary. Finish the job before publishing. Note that this development flow relies on the decoupling of the creation and the publication of changesets. This is a distinguishing feature of distributed revision control systems versus centralized ones.

When you are ready with your changes, you can use mercurial to publish them.

To see the changes between your local repo and the parent repo it was cloned from, use:

hg out

The typical way to propagate such changes from one repo to another in mercurial it to use hg push. Except, this won't work for the MyHDL Source code repository. With mercurial you can't push to a repo specified by an http url. Moreover, I wouldn't let you As explained earlier, I want to review the changes before applying or rejecting them. Instead, use the following:

hg bundle <bundlename>.hg

Think of hg bundle as an hg push with me in the middle It does a similar thing, except that you have to send me the bundle file and let me do the push (after reviewing).

Send the bundle file to Jan Decaluwe.

Keep any technical discussion leading to the bundle on the mailing list. Only the final operation of sending the bundle file should not go there. That having said, I can imagine advanced scenario's in which people exchange bundles on the mailing list as a means to convince others about new features.

When logging changesets and browsing through the repository, mercurial uses only the first line of the commit message. Therefore, the first line of your commit message should be a short, descriptive one-liner. There's nothing against a more verbose message (on the contrary), but start it on a new line.

Use .hg as an extension to your bundle file. This is a convention among mercurial users.

Bundles have a slight inconvenience: after creation, it may not be straightforward to review their contents. For example, suppose you do:

hg in <bundlefile>

within the repository where you created the bundle. Then nothing would be listed, because your repo obviously has the changes already.

To review changesets in a bundle, you have to move to a repo that doesn't have those changesets yet. If your target is a remote repo, the workaround is to create a local clone and run the hg in command from there.