Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
What if I think, that I found a bug in an open-source-app? What steps can I do, to provide as much helpful information for the programmers, as possible? And how I report best, to avoid to be annoying for the programmers?
Addition: As some here say, that the OS-programmers will love the report: Some projects are very picky about bug-reports. They say that are non-bugs or that it is non-reproducable, or the way it behaves is intended or similar things. Some of that critic towards the bug-reports may be justified, but often it isn't. I want to 'optimize' the bug-report to get the best feedback (preferably a fix) out of it.
The minimal information that I as a FOSS developer would like to get from someone submitting a bug report is:
software version
platform
brief description of the bug
sample input that you think is correct
sample output that you think is incorrect (and why you think this)
Exactly how you go about supplying the information will vary enormously from app to app. Before posting the bug, you should take a look a the support newsgroups or mailing lists to se how this kind of thing is handled.
Edit: If the bug is non-reproducible or intended behaviour, I don't think you will be getting a fix, no matter how you optimise the report. But you do always have the option of fixing it yourself if you are utterly convinced it is a bug.
First, go on the project page and check for information on how to report bugs. They might have a preferred way of doing it.
Most projects have mailing lists. Most of them have a user and a developer mailing list. Start by searching the lists to see if the bug you have discovered was already discussed. Maybe it's not a bug and the product simply does not support what you try to do.
If you have already digged in the code and found the cause of the bug (and maybe the fix), subscriber to the developer list and post a message describing the problem. Include a complete description of the problem, the version you use (and the version of other software if needed. ie.: Web server, OS, ...), a test case, what you found in the code and the patch you made. If it's a bug, they will tell you to report it in their bug tracking software (bugzilla, mantis, redmine, track, ...)
If you don't find anything in the code, subscribe to user list and post your problem.
Avoid saying thinks like "please, I really need to fix or I ...". Open source developer are not your employees. If you want something fixed, you can always do it yourself. Avoid ultimatums and rant about the software.
If the bug was already reported, the only thing you can do is watch it or vote it up. Avoid adding comments like "me too!" or "we need this fixed!" or "why is this still not fixed?!?". That is annoying.
Find the bug system (for example, https://bugzilla.mozilla.org/ for firefox) If you can't find any links off the main page or from google, you may have to use one of the projects mailing lists or forums. Poke around a bit and find the most appropriate one to use.
Once you have figured out where bugs should be reported, do a search to see if your bug has already been reported. If it has, see if there is anything you can add that would be helpful (me too! comments are not being helpful, additional information is very helpful)
When it comes what to report, first list your environment (operating system, what version you are using, where you got it from, etc) Describe the bug (what is going wrong), and give detailed steps on how to reproduce it
For general advice about reporting bugs (what information to provide, etc) I recommend Simon Tatham's paper: http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
A. They will love to hear from you, this is not annoying.
B. describe exactly how you can reproduce the bug, what steps, what OS, what else is running on the system.
C. look at the open source project's site - it probably has an address to submit this kind of info.
Find the application's website. There is usually information there about bug reporting procedures, as well as bugs that have already been submitted (so that you don't submit a duplicate). Error messages, screenshots, and steps to reproduce are what I always like to have when I am trying to track down/fix a bug.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
I've been holding off on releasing a library I wrote because it is the first library which I'll be releasing publicly. Here are my concerns:
The library isn't complete it is in a very usable state, I'd say it is version 0.3, however it still lacks a number of features which I would like to at some point implement, and control how they're implemented (meaning not merging someones implementation).
I'm fearful of criticism, I know there are a few things which should be reorganized/refactored, but I wrote the initial class quickly to be functional for another project I am working on.
So when is the best time to release? Should I just throw it up on github and work on the issues post-release? Or should I wait until I refactor and feel completely comfortable with what I have written?
Most classes/libraries I see are always very elegantly written, however I have not seen any in very early release stages, are a lot of classes fairly sloppy upon initial release?
Release early, release often.
Criticism is a good thing as long as its constructive. Ignore the haters, pay attention to the folks filing bug reports and commenting.
The internal structure of the code matters, but it matters more if it works for its intended purpose. In general, refactoring will change how code works internally but will not affect how it is used. Same inputs and outputs.
You need to get something half-way
useful first, and then others will say
"hey, that almost works for me", and
they'll get involved in the project.
Linus Torvalds
Linux Times (2004-10-25).
It depends on why you are doing this. If it's to provide something useful and it's useful and has benefits that no other library has, then go for it. Just list the status and what's coming next.
If you are doing this to point to on a resume, get it in good shape (the code, not necessarily feature complete). Imagine a future employer poking around the code to see what it looks like, not downloading and running the code.
Whether you release the code in an incomplete state or not, it's always worthwhile having enough documentation to allow users to understand how to use the library.... even if it's only API docs. Make sure that anything incomplete is tagged as TO DO - it helps to maintain a target list of tasks to complete, and lets users know that the feature/method/whatever hasn't been forgotten.
Providing a set of code style/standard documents (perhaps with architectural notes on class relationships) allows other developers to contribute more readily, and in a manner that enhances the library rather than making it a hotch-potch of spaghetti code. It's never easy releasing a library, then having to refactor, while maintaining backward compatibility for users who have already taken up and are using that library in a production setting.
EDIT
Don't be afraid of criticism... it goes with the territory.
Some critcism can be constructive (take heed of that).
There'll be plenty of other people who criticise your code (for whatever their reason) without being constructive, or who just denegrate your work. The difference is, you've produced the goods, they probably haven't ever contributed to any OS product/library.
Users expect you to fix their problems immediately, or to write their code for them to use your library, or simply say "it doesn't work" without any explanation of what they mean. You have to learn to live with that 24x7x365.
But just once in a while, somebody will thank you for saving them hours of work, or for providing something useful... and suddenly all the stress and hassle feels worthwhile.
I read a document by Joshua Bloch, a pricipal software engineer at Google that talked a lot about the best type of API design. Basically, once you release it, it is more or less set. He says
Public APIs are forever - one chance to get it right
You can check out the slides here. It's definitely worth reading. I have a PDF of it as well; let me know if you need it.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 9 years ago.
Improve this question
I'm working on an application and I needed an API wrapper for it. I noticed that most of the API calls I needed weren't implemented, so I went ahead with adding them in. There are a few bugs that need fixing which I'm planning to fix as well.
My problem is that development of the wrapper is almost non-existant at the moment. A bug submitted with a patch from October 2009 has been ignored so far.
I've emailed the main developer so I can commit my changes or even submit them somewhere, since on the homepage, it said that he's the person to contact with this sort of stuff. I've also asked about this on the discussion board, with no response.
My question is, how long should I wait for a response before forking this wrapper? It's one of only two open source wrappers for this API and listed on the API Doc's page. I hate to see that there's no improvements to it.
So, how long should I wait. What's normal for this kind of thing?
In case it matters: the licence is Simplified BSD
UPDATE:
The original developer finally responded; so I didn't end up forking. Apparently he was just very busy with work.
A good (relevant) article to read for anyone coming across this question: http://dashes.com/anil/2010/09/forking-is-a-feature.html
And thanks to everyone for your answers!
You can fork any time you want. Once I was in similar situation. As I had informed project admin that I'm going to fork, I obtained a response and it wasn't necessary :P
BTW I have written to sourceforge crew (project was hosted on sf) and that was their advice to fork.
Perhaps I am a little late but would like to answer on the level of definition.
The term Forking (branching away) refers to a split between groups and development in different directions. In this case a branching away can not clearly be seen so there was not actually a forking of a product. The action was clearly an alteration (extension) for a personal need. Should a product experience alterations and the result again be returned to the group it comes from is forking also not the proper definition. By definition open source encourages you to alter.
It depends if you plan to maintain your fork. If you do then the chances are it will become a better project than the original. Otherwise maybe wait a couple of weeks. Still, even if you released today there's nothing to stop the original project merging your changes so the community as a whole benefits either way.
There's no protocol, just call your fork something else and give the original prosjekt plenty of kudos for the original work.
Forks happen all the time, it's not necessarily a 'divorce' with the origial maintainers ... just happy coding.
Your additional calls might be usefull for someone else, but then again it might not.
Does the project has a publicly known mailing list/bug tracker, and if is - is it affordable to submit a patch there? Also, can't be a developer - become a maintainer at one of popular Linux distros, (submit a Gentoo bug/Launchpad entry).
If there's no sense in such actions - just fork.
Sounds like you've done the right thing though and tried to stay within the existing branch and now it is appropriate to fork.
If nothing else, forking is a more powerful action than most other things i.e. if you fork and still don't get the original developer's attention then you can be satisfied that you did the right thing. Of course once forked, there's no real reason why there can't be some convergence at a later stage.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
This may sound like a foolish question or an observation, but i have seen that most of the times when one tries to look at the opensource code, there are no comments or just one or two lines at the start of the function telling what the function is used for e.g. register a user or data in table etc. There is no code which actually explains what exactly the function is doing etc.
Is it done intentionally (removal of comments) when a code is released to open source community to make things difficult to understand by others?
There is a line of thought that says that comments are unnecessary when the code speaks for itself. I don't believe comments would be removed on purpose, though.
I've seen both sides, and frankly code in general is insufficiently documented.
I've been congratulated and thanked for leaving copious breadcrumbs but that's because I've had to sift through too much undocumented code to want to subject anyone else to it.
Call it an ethical obligation.
My reason to document code: my short-term memory is junk. I write comments to remind myself of why I did something. Everyone else benefiting from that is gravy.
I don't think there is a practice or policy to remove comments when releasing software as Open Source. A sneaky software publisher might think that a good idea (maintaining de facto exclusivity, because nobody can't understand it, while having released an open source product) but this would cripple the Open Source project from the start and most likely render it unusable.
The code you are talking about is probably just very little documented. As ocdecio says, that can be either a good sign (the code speaks for itself and does not need comments) or a bad one (it is badly documented, bad code). Both cases are entirely possible. :)
What are you comparing it to?
I doubt that closed-source code has better comments.
As for what functions do, there is probably API documentation. No need to duplicate those in comments.
As a rule, functions should be small enough and written in a way that allows working out how it works by just reading them. A comment on top of the function describing what it does helps getting a quick overview of the function itself when reading through the whole source code file (unless the function name speaks for itself).
Many projects are organized in that way, and that is great.
However, what I am often missing when trying find my way around a larger codebase is something describing the big picture, i.e. the general architecture, principles, what goes where and similar things.
All open source is not made the same. This is what we call a generalization.
If you look at the website Ohloh, which tracks a very large amount of the open source software in existence, it paints a much different picture:
http://www.ohloh.net/languages?query=&sort=code
For instance, in the C language, there are 252+ million lines of comments, approx 1 in every 5 lines of C is a comment. For Java, nearly 1 in 3 lines is a comment. That's not bad.
Open source software has bad comments and bad documentation most of the time. There are various reasons why, some better than others. Usually they relate to laziness or the developers 'being in the moment'. None of the reasons are good reasons.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
I write hobby code from time to time. The thing is these tools, classes or tiny libraries of code end up in a flash stick with hopeless future! I would love to develop my projects further, and let other programmers trust them. If you were going to use something you found on the Internet, what is the most important thing you look for in that programming tool or small library? e.g. would you consider separate documentation a must?
Thanks for all contributers. I'll try my best to summarized what have been said. Feel free to modify the list. Corrections and additions are more that welcome :)
Start a blog and let others know you
are here.
Choose the most
suitable license. Possibly Open
Source licenses are the best for
hobby projects.
Put your project where people can
reach it. Consider google-code,
github, sourceforge or
other sites.
Use public version-control and
bug-tracker, So others can acquire the
latest source code of your project to
compile and use.
Write a decent documentation, beside
commenting your code clearly of
course. The documentation should
explain the purpose of the library
and provide at least simple examples.
Write tests if you are willing to provide real-world code.
If you are building a library, put a
lot of effort into designing a stable
interface.
Get a blog, release code through it. Explain why you wrote it, what problem it solves. And encourage others to improve upon it, keep the code posted as current as possible. If your tools are useful you will very quickly develop a following that 'trusts' your code.
Separate documentation isn't a must for small tools, but anything creeping into the framework world should probably have ample documentation and examples if you want any serious adoption from the community at large.
The most important thing is that the library is that it be open source, so I can read the code myself. If that is not possible then I insist on documentation.
Also consider using a project-hosting site (like google code or github).
Have a clear license with your code if you don't have one already
(preferably one which encourages modifying / improving / sharing your
code ...)
Have public version control and/or a public bug/issue tracker and/or a mailing list. There are a lot of good sites which offer these services for free.
Seperate documentation is not a deciding factor to me (if the code is well documented and the code quality is high).
Documentation explaining why you wrote it, when you started it, and it's intended function. Understanding where you're coming from will allow me to see future ideas as well as short coming you may not have seen.
Technical documentation explaining the API and some examples on how to implement it. Ideally, keep your documentation in the format that follows the language. For example C# tends to use the XML syntax for defining items. This allows me to feel at home when I'm reading it.
Clean code -- I can't stress this enough because far too many people write exceptionally ugly code. If you're code is ugly and/or unreadable, it may be easier for me to write it from scratch on my own. At the very least, make your code consistent. If I can't understand the code, I won't feel comfortable with it.
Historical records explaining your changes. Seeing how the project has grown allows me to plan better. It also allows people to see how you learn from your mistakes and get a sense of your skill level. Compared to a forum, you can get a feel for how fast things get fixed and then placed in to a new release.
Think long and hard on what kind of license you want there. Public domain? BSD? GPL? More restrictive?
A note on whether or not you mind being contacted and if there are any restrictions in this. For example, would you mind updates? Me explaining security holes? Or perhaps you might use a forum or wiki?
The ability for me to get your latest work and/or nightly builds. SVN or something. This is useful so I know if a bug I found is already fixed.
I think that documentation is a key point for your project.
The document must indicate:
what is the purpose of your library
what are the main features
a really short tutorial, to make it run in 5 minutes.
Many examples
I let people trust my code in a number of projects, but I urge people to make and maintain their own tests, and I make sure that I'm content with the unit tests.
Documentation is always good, but I'm very guilty of finding time to do as much as I would like. But having the author fairly contactable is helpful.
Posting it in an open source repository such as code.google.com or sourceforge.net is probably where to start...
Next to attract attention, document clearly and succintly the purpose of the library / application as outline in one of the answer above.
Finally, blogging and direct mail exchanges happen...
One reason documentation helps people trust your code, is that they know whether a given feature is something which you intended the code to do (and which you will, all else being equal, preserve in future versions of the code), or something that the current code just so happens to do, but which might change at any time as a side-effect of a bugfix or just a refactor.
Some people prefer find out what code really does by looking at it, and that's fine, but documentation tells you (a) what the code is supposed to do, and with any luck (b) what the next version of the code will do. If I want to use your code long-term, and take bugfix updates as you provide them, then I need to know that you've designed an interface that I can rely on and that you're willing to stick to. Documenting it is a strong hint that you're at least trying to do that.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
What is the most useful strategy when your application throws an exception in the middle of the demo, in terms of keeping the client's mood still positive?
If your client doesn't trust you, there's nothing you can really do. I build trust with my clients so when something like this happens, they believe me when I give them an explanation. And when I tell them what I'm going to do to prevent future problems, I make sure to follow through.
Depending if this is a "final" demo or if its a mid-project demo will also affect whether you can really alleviate the customers' concerns. There's very little you can do to make the customer happy if it's the end of the contract and there's no more budget for testing and bug-fixes.
One generic strategy I've used: if you have someone in the room document the exception/problem in front of the customer and let them know it is going into the bug tracking system for investigation and testing, that will demonstrate to them due-dilligence and alleviate some concern. You, of course, need to follow through and make sure to fix the problem.
Just tell the truth but humorously, like saying apparently our software is still not that perfect, and we are keeping making it perfect.
don't ever lie or try to cover it up. clients are not dumb.
I'd say it depends on what stage you're in. If you're selling something, my experience is that it is always preferable to just bring static material for demonstration. Powerpoints are alright, but printed screenshots that the clients can toss around the table are unbeatable. It allows you to only show exactly what you want, in a very controlled manner, while still looking very professional.
If the client has already bought the project, and the demo is related to, say, a launch that's coming up, the best you can do is to smile and say "as you can see, we're still working out a few quirks"
I usually let the client know up front that I'm running off a live dev environment so we might see some weirdness. If I am aware of parts that have issues (inconsistent crashes..) I let the client know about them before I show that section (along with the fact that production won't do this and I am working on it already).
Update: based upon other responses, I agree that early demos with static material are better for generating discussion.
The last time I presented a project to a conference, I planned a live demo, but I actually had a set of slides headed "If you can see this, the live demo didn't work!" with big screen shots. Inevitably the live demo didn't work (it needed a globally routable IP address and this wasn't available) and the slides were called for.
I think it personally depends on your relationship with the client and how satisfied they are with your product this far.
I usually tell them it was bad data from testing or jokingly say that was a test to see how the application handles errors (if you have a generic, catch-all error message/page). You can also use the time to reiterate the importance of user testing/acceptance.
I've never done a demo where I didn't set expectations beforehand. If this is a work in progress, make sure they know that up front. This goes a long way towards keeping them positive. EVERYBODY has issues during demos. Just smile, tell the truth and continue.
Probably the best way to help keep your client positive is to project positivity and confidence yourself. If you seem unsure of yourself it'll show as being unsure of your app.
Possible strategies:
Telling the audience "we're all going to stay here until whoever did that owns up".
Complaining about the prevalence of evil monkeys.
Seriously, I'm majorly against public product demos. Don't attempt demos until you're 99.99999% sure the damn stuff works. And even then it's a bad idea, you're setting yourself up to fail with all the variables that can go wrong - which may not even be with your software. If you must do it, attempting to impress customers with a flashy UI is best done one-on-one. That's the way we've always done it.
Is this shipping product or still under development?
Assuming it's a shipping product, just recover and move on. Work the room while recovering (rebooting, restarting the app, etc.) and don't dwell on what happened. Customers understand stuff happens.
I was an applications engineer and this happened frequently. IMO, the key to recovering from this starts at the beginning of the relationship / sales process / demo, not one particular event. Establish trust and build credibility with your audience as early as possible. If you have this and an exeption gets thrown, the audience will probably trust you enough to think nothing about the software failure and just move past it. Yeah, you will have the occassional person looking to crucify you regardless of what you do but that comes with the territory.
Be honest if someone asks (they probably won't) and never talk negatively about your product. I also found when questioned about a fatal error, it helps, and they are very foregiving, if you can explain what happened in terms the audience understands. It demonstrates your knowledge of the software process and goes back to trust.
Write down the Exception and why/how it occurred IMMEDIATELY. Then they will see that you will be fixing it.