On Wed, 2014-01-22 at 09:34 +0100, Łukasz Stelmach wrote: > Hello, > > Is it OK to push changes to changelog directly to refs/heads/tizen and > bypass a review?
I do not know what is the "official" guidance, but I've just always be doing this for packages I maintain. While on it, here are related statements I feel strong about. And then explanations too. 1. Maintainer should never require developers to provide the changelog changes. 2. Maintainer should write the changelog entry before submitting the package to OBS, and it is OK to just push it directly to the branch without gerrit review. Now some explanations. First of all, just a reminder, that developer and maintainer here are just roles. I am developer for some projects and maintainer for other projects, for example. Also, just a reminder, that a developer is a random person from the Internet, in general. Of course, we mostly have good developers here who are also maintainers in other projects, but anyway, in general, it is just a random person. Now, about changelogs. This is very important in my opinion. I never posted my thoughs to the public tizen mailing list before. And I decided to write because I am curious about what my Samsung colleagues think, and also I sometimes see changelogs which make me shudder. There are 3 types of "logs"/"changelogs" we see in tizen.org. 1. Commit message. Produced by developers. The customer is other developers. Should start with explaining the _motivation_ for the change. Other developers have to understand _why_ is the change. If I spend more than 5 seconds figuring out whether the change is a bug-fix or a clean-up - the commit message is no good. Then it should explain all the details, if needed. It is also important to have a good commit subject. I love this blog-post and recommend as good reading: http://who-t.blogspot.com/2009/12/on-commit-messages.html 2. Packaging changelog. Produced by maintainer. This can also be produced by a developer, but should be carefully read and if needed, amended, by the maintainer. Customers are the Tizen _users_. Users do not necessary know anything about Tizen internals. In practice this means that packaging changelogs should only contain high-level information, like which JIRA bug numbers are fixed, which new features are added, what was significantly improved, which functionality was removed, etc. When I see people writing about which variable they renamed in the packaging changelog, I get very upset. This is not the right place for things like that. Or I sometimes see people writing HW register names in kernel changelogs. I get upset too - this stuff should only be in the commit message and/or commentaries in the code. And I see stuff like this often at tizen.org. Sometimes I see people adding a changelog entry which copies/mirrors their git commits. This is no good too. Users usually cannot read this. Packaging changelogs should be user-friendly and readable. Ideally, you should be able to use packaging changelogs like this. Suppose you release Tizen Mobile version Y, and the previous version was X. You go and collect all the changelogs from X to Y from all the packages, and include this to the Tizen Mobile version Y release notes. Obviously, this would require maintainers to put a lot of efforts into making changelogs really readable. So this is why, in my opinion, it is important that the _maintainer_ carefully produces packaging changelogs. Simply because an average developer cannot do this properly - it is not easy, developers are not necessarily trained to do this. Again, developer is just a role. If a developer send the maintainer good quality changelogs - great! But this should be optional. And this can be an indication that the developer is getting ready to become a maintainer. Sometimes I see that people think that there should always be a packaging changelog entry. E.g., they remove a bunch of trailing white-spaces and think this is worth mentioning in packaging changelog. No, this is not! Another example. It may be perfectly valid to have, say, 1000 commits, and only one short changelog entry like "improved FPS from 30 to 60 by implementing HW acceleration support". This all depends on what's in those 100 commits. 995 of the commits may be just preparational, like code re-structuring. And the last few commits may actually added the HW acceleration support. And in my opinion it makes really little sense to require maintainers make the changelog entries go through gerrit review. This is only a burden and an unnecessary delay for the production. Of course, if the maintainer is a newcomer and wants peer's review - fine, but this should be completely optional. 3. This is minor, but there is also the OBS "changelog", or you name it, as "msg" in 'gbs submit -m <msg>'. Produced by the maintainer. Customer is the release engineer. This one should just give a very short summary of what is sent. It does not have to repeat the packaging changelog, because the release engineers will see the packaging changlog diff anyway. This is just a short hint to the release engineer which tells what is the submission about, nothing more. Thanks for reading this far. And at the end hint for writing decent changelogs: when writing, always remember about who is the customer - the user or other developers. -- Best Regards, Artem Bityutskiy _______________________________________________ Dev mailing list [email protected] https://lists.tizen.org/listinfo/dev
