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
What do you do with GitHub repositories you no longer maintain?
For whatever reason a project is started with a GitHub repository and then sometime later it's abandoned Perhaps it was an experiment that didn't work out. Perhaps you replaced it with a commercial product. Or perhaps you found a similar project to what you were doing and joined their efforts instead.
In the time your repository was alive, it attracted watchers and a few forks.
What do you do with it at that point? Is there a way to nicely indicate that repository is no longer maintained and to either check out the forks or a different project?
I'd do a single commit that removes all the source except for a README file that clearly states that you no longer have interst in the project (also copy the important parts of the README to the last commit log message, use git commit --amend if needed).
The README should explain that all the source code is still available as history. In addition the state of latest code should be described for maturity level: if it was used in production somewhere, it should be said here. If it was only an experiment and you never got it to compile correctly, then that should be said in capital letters. In the latter case, it might make some sense to just remove the code repository, though.
Obviously, the README should also contain the generic description of what your code does, but that should be already in the README.
Also try to put some words in the README that you expect potential users of that code to look for. Try to put those words close to the part that says that you're no longer maintaining the code.
The reasoning for this:
anybody interested in your source will still be able to get it (through history)
anybody trying to blindly merge your HEAD with his will immediately see that it's a bad idea (all source code will be removed and replaced with a README that explains why this happened)
I don't agree with the suggestion that if nobody has forked (and preserved the code), it's worth nothing. Perhaps the only reason somebody else has not taken over is that your project haven't been seen by enough many eyeballs.
If you believe that your code has any value (and I do mean anything above zero), then do not delete it. Just make it clear that the code has been abandoned.
Actually, I think pretty much the nicest thing you can do is to simply delete the repository. That way, the obsolete code doesn't show up in searches, for example.
The whole point of distributed version control is that no single repository is more important than another. If there is enough interest in the project, then one of the people who forked the repository will emerge as the new community leader. And if nobody forked it, then it probably wasn't worth preserving anyway.
I'd make a nice commit in the README file which basically states that this is here for historical reference, look at X Y and Z in order to see where this code went.
I prefix my projects with "deprecated." There are some posts on github's site regarding this, but it seems they won't budge. They want you to put a note in the readme. I'd prefer to put information in a relational database so you can sort on different fields, one of those being if the project is active or not.
I put my deprecated projects up there because there are concepts you can re-use. It is similar to your school work. Hopefully you can learn a lesson or 2 from it.
Walter
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 5 years ago.
Improve this question
Often there are situations where a project is passed on someone else. And often this process is unpleasant for both sides - the new owner complains about horrible documentation, bugs and bad design. The original owner is then bothered for months with questions about the project, requests to fix old bugs etc.
I might soon be in a situation where one of my projects will be given to someone else so I can focus on my other projects. I wonder what should I do to make this transfer as smooth as possible. What i already have is a decent documentation, the code is quite good commented and i'm still improving it. Its a medium sized project, not very large but still its not something you can code in a week.
I'm looking for a list of things that should be done in order to help the future owner taking over the project and at the same time will spare me all those annoying questions like "and what does this function do, what purpose does this class have...". I know documentation is a must - what else?
Note: although my project is in C++ i believe this is a language-agnostic question. If there are things you think are specific to some language, please mention them too.
Documentation is one thing, getting it into the head of your new project owner another. IMHO this is a typical situation where "less is more" - the less documentation your colleague has to read to understand something, the better. And, of course, learning takes time - for both of you, accept it.
So
instead of writing lots of documentation, make your code self-commentatory
have all documents / source code etc. in a clean and well named folder structure
make sure your build-process is almost completely automatic
don't forget to document your deployment process, if it is not automatic, too
clean-up, clean-up clean-up!
When taking over a project, documentation is of course desirable, but even more so is a good test suite. Trying to modify a program that you have no means of testing for correctness is a nightmare.
Documentation, but on all levels:
API docs
High level architecture: What components are there, what are their relationships and dependencies
For each component, a high level description pointing to important code sections
Tutorials: If you want to do X, here's how
Data: What data does it use and how, database schemas
Idioms: If you've created some idioms within your code, explain them
And, to start, give the guy a personal introduction to all of the above in person, hopefully doing some needed change in a pair programming way
the new owner complains about horrible documentation, bugs and bad design.
I suspect that no matter what you would do, new owner will always complain about something. People are different, so something that looks easy to understand for you, will look horrible and extremely complicated for someone else.
The original owner is then bothered for months with questions about the project, requests to fix old bugs etc.
In this case you should clearly refuse to help. If you won't refuse, you'll probably end up doing someone else's job for free. If maintaining the project is no longer your job, then the new guy should fix his problem without your help. If "the new guy" can't deal with that, he isn't suitable for the job and should quit.
Its a medium sized project,
"Medium sized" compared to what? How many lines or code, how many files, how many megabytes of code?
I wonder what should I do to make this transfer as smooth as possible. What i already have is a decent documentation, the code is quite good commented and i'm still improving it.
I would handle it like this:
First, do a sweep through the entire code and:
1.1 Remove all commented out blocks of code.
1.2 Remove all unused routines and classes (I'm talking about "forgotten" routines, not parts of utility library).
1.3 Make sure all code follow consistent formatting rules. I.e. you shouldn't mix class_a, ClassA and CClassA in same app, you shouldn't use different styles for putting brackets, etc.
1.4 Make sure that all names (class, variable, function) are self-explanatory. Your code should be as self-explaining as possible - this will save you from writing too much documentation.
1.5 In situations when there is a complicated or hard to understand function, write comments. Keep them as short as possible, and post only when they are absolutely necesarry.
1.6 Try to make sure that there are no known bugs left. If there are known bugs, document them and their behavior.
1.7 Remove garbage from project directories (files that are not used in project, etc.)
1.8 If possible, make sure that code still compiles and works as expected.
Generate html documentation with doxygen. Reveiw it few times, modify code comments a bit until you're satisfied. Or until you're somewhat satisfied with the result. Do not skip this step.
If there is a version control repository (say, git repository) with entire development history, hand it over to a new maintainer, or give him(her?) a functional copy of the repository. This will be useful for (git )bisecting and finding source of the bugs.
Once it is done, and code is transferred to a new maintainer, do not offer "free help", unless you're paid for it (or unless you get something else for helping, or unless it is order from your boss which makes helping new maintainer a part of your current task). Maintaining the code is no longer your job, and if new maintainer can't handle it, he isn't qualified for the job.
I think most of the problems can be avoided with just two simple rules.
Keep the code consistent with platform style guide.
Naming, naming and naming.
If the project is huge, then you just need to run some code camps with the new guys. There's no shortcut for this one.
Remember also that complaining happens mostly because new guy is not qualified enough, i.e. doesn't understand something. That's why it is important to keep things simple. And in case he is more qualified, then I guess you deserve it ;)
Some good advice where to start hacking/changing things is always better than documentation. Consider documentation as a backup material after you are familiar with the code, it should never be the starting point (except if you are exceptional technical writer with unlimited resources and time)
If there is good documentation and commented code as you say, then you've done your part. Just make sure that the documentation includes high-level documentation (architecture, data flow, etc.) as well as lower module or procedure-level documentation.
If this is a situation where you can, I would strongly suggest you protect yourself with some type of contract that specifies what future support (if any) you will provide and for how long.
I think for a situation like this the most important thing is a working, complete build that automatically compiles, documents, and tests the project. That way, there is a well defined point at which the new developer has it working. He can then figure stuff out from the tests and documentation, in principal.
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 8 years ago.
Improve this question
This question is about etiquette and open source projects.
I have forked an application from github and added two new features.
The first feature has been request frequently elsewhere. I have added it. Code & implementation are clean (I think).
The second feature is more of a hack. It will be of use to others, but the implementation is a little dirty in useage and more so in code. I need the feature but I don't have the skills to fully implement it properly or to a level that could be considered a worth while contrabution to the main project.
How should the versioning work? Do I just bump up my version numbers care-free and push to my master branch?
It is annoying to know which version is running, modifed or original, as both have the same version number. But will it be confusing when, months later, my github page has a version number the same as the original but both are actually completely different. (I have made pull requests etc. but that is not the context of my question.)
The project I have forked uses ruby jeweler so has a versioning format of:
Jeweler tracks the version of your project. It assumes you will be using a version in the format x.y.z.
x is the 'major' version, y is the 'minor' version, and z is the patch version.
Is this standard for other projects/langauges too? Are my changes patches?
Thanks
This can't be answered easily. Version number handling varies between projects and your goals. Do you see your fork as a temporary issue? - Then, in many cases (might be different with larger rewrites for example), I won't increase the version number as it is up to the project leader to do.
Many versioning schemes allow to extend the version number to something like 1.2.3-ross, which helps users filing proper bug reports.
If you plan a longer running fork you should find a versioning scheme which works for you.
Different pieces of software from the same code base but with different feature content should have different version numbers in some way - so you need to change something in the version number (or product name).
Do you plan to submit the first change back to the project? (You probably should.)
Is the second feature, the hack, one that you will improve over time? You might keep it on your own development branch so it is easier to maintain separately while still importing updates from the main project.
Or are you planning to stay separate from the main project in perpetuity? In that case, you should consider renaming the software as well as changing the version - or somehow making it clear that the version is yours and not theirs.
If you intend to fork, which is to say never merge back with upstream, then consider renaming your project.
Otherwise, it's common to use a version number that indicates the branch and changeset being ran ala -git-ross-12345
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 8 years ago.
Improve this question
I find myself wanting to develop certain projects, but most of the time I lack motivation because I develop by myself.
What I usually do is look for similar existing projects, and ask the developers if they like to collaborate, but it's rather hard.
Is there a good place (a website maybe) to find people that are interested in the same project as me, and therefore would like to collaborate?
You code by yourself?
Release the code on one of the open-source foundries. (code.google.com. sf.net. bitbucket.org , github.com ,etc...)
Pick an easy license (x11/MIT is good, GPL2/3/AGPL3 if you like, among others.)
Write simple instructions on how to deploy, run, with a one-page tutorial.
Have a website where you write about the stuff you build, and the stuff you'd like to build.
Find people who need some help and help them. Don't over-extend yourself.
It takes time to build trust. Trust takes time.
Update
You wrote:
What I usually do is look for similar existing projects, and ask the developers if they like to collaborate, but it's rather hard.
If you see an open-source project out there, odds are the developers already like to collaborate. What they might not want to do is talk about grand schemes about how to turn the software into the next fifty billion-dollar behemoth. Generally, if you join the mailing list, introduce yourself ("Hi, I'm Joe, and I like to do X, and I like this software."), get and use the software, and provide feedback and constructive criticism, and demonstrate that you are following instructions or at least attempting to, and then, then, if you provide a patch (or a branch if github) it might be looked at and considered.
Do follow the project methodology. For example, if they use tests, submit tests with your patch, that sort of thing.
I tried myself to start an open source project and failed. I had published my idea in a forum and there were about 10 or 15 people who wanted to join the project. Actually there were very little activity ...
I think the main reason for the failure was that I hadn't developed anything before going public. It would have been really useful to have at least a prototype. Another thing is defining a (simple) development process.
If I would try it again, I would:
develop a prototype
document the code and the architecture in detail
write down tasks others could do
describe the development process
design a nice website and promote my work
publish the code at google code or something like that
Check out the offerings at github.com. If you can use git, I often find some cool projects on there, and you can always fork the repository to help out.
First, you should register your project on an Open Source Forge. There is a comparison list on Wikipedia : http://en.wikipedia.org/wiki/Comparison_of_open_source_software_hosting_facilities
On certain forges, there is a way to ask for help. I know that SourceForge does: https://sourceforge.net/people/
I recommend that you read Karl Fogel's excellent and complete book on the subject : Producing Open Source Software. It is freely available online or in print from Amazon.
If you already have some code somewhere online, you could put an ad for your project on Stack Overflow's Open Source Advertising.
Quote from the link:
It must be an advertisement soliciting the participation and
contribution of programmers writing actual source code. This is not
intended as a general purpose ad for consumer products which just
happen to be open source. It's for finding programmers who will help
contribute code or other programmery things (documentation, code
review, bug fixes, etc.).
Openhatch
is the best place I have found to look for open source projects