Skip to content

Instantly share code, notes, and snippets.

@jeffkreeftmeijer

jeffkreeftmeijer/notifications.png Secret

Last active January 7, 2021 16:48
Show Gist options
  • Save jeffkreeftmeijer/aa1d6d6793b592e67b108867115d13f6 to your computer and use it in GitHub Desktop.
Save jeffkreeftmeijer/aa1d6d6793b592e67b108867115d13f6 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. jeffkreeftmeijer revised this gist Jan 7, 2021. 1 changed file with 4 additions and 0 deletions.
    4 changes: 4 additions & 0 deletions open-source-maintainability.adoc
    View file
    Original file line number Diff line number Diff line change
    @@ -4,6 +4,10 @@ Jeff Kreeftmeijer <https://jeffkreeftmeijer.com>
    :description: It's impossible to predict if you'll have time to work on your open source project in the future, but there are ways to minimize the amount of maintenance it requires.
    :url: https://jeffkreeftmeijer.com/open-source-maintainability/
    :image: notifications.png
    :revisions: https://gist.github.com/jeffkreeftmeijer/aa1d6d6793b592e67b108867115d13f6/revisions
    ifdef::env-github[]
    :imagesdir: https://gist.githubusercontent.com/jeffkreeftmeijer/aa1d6d6793b592e67b108867115d13f6/raw
    endif::[]

    If your open source project gains popularity, it will stay included in other
    people's projects and workflows for years. It's impossible to predict if you'll
  2. jeffkreeftmeijer renamed this gist Jan 7, 2021. 1 changed file with 0 additions and 0 deletions.
    0 index.adoc → open-source-maintainability.adoc
    View file
    File renamed without changes.
  3. jeffkreeftmeijer revised this gist Oct 15, 2017. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion index.adoc
    View file
    Original file line number Diff line number Diff line change
    @@ -1,4 +1,4 @@
    = Keeping open source projects maintainable
    = Keeping open source software projects maintainable
    Jeff Kreeftmeijer <https://jeffkreeftmeijer.com>
    2017-09-19
    :description: It's impossible to predict if you'll have time to work on your open source project in the future, but there are ways to minimize the amount of maintenance it requires.
  4. jeffkreeftmeijer revised this gist Oct 15, 2017. 1 changed file with 2 additions and 0 deletions.
    2 changes: 2 additions & 0 deletions index.adoc
    View file
    Original file line number Diff line number Diff line change
    @@ -10,6 +10,8 @@ people's projects and workflows for years. It's impossible to predict if you'll
    have time to maintain your work in the future, but there are ways to minimize
    the amount of maintenance your project requires to remain useful.

    image::notifications.png[Keeping open source projects maintainable, 1200, 675]

    == Don't add or merge features you won't use yourself

    > It didn't take long to add support for another database management
  5. jeffkreeftmeijer revised this gist Oct 14, 2017. 2 changed files with 7 additions and 5 deletions.
    1 change: 0 additions & 1 deletion _metadata.yml
    View file
    Original file line number Diff line number Diff line change
    @@ -1 +0,0 @@
    image: https://jeffkreeftmeijer.com/open-source-maintainability/notifications.png
    11 changes: 7 additions & 4 deletions index.adoc
    View file
    Original file line number Diff line number Diff line change
    @@ -1,13 +1,16 @@
    # Keeping open source projects maintainable
    = Keeping open source projects maintainable
    Jeff Kreeftmeijer <https://jeffkreeftmeijer.com>
    2017-09-19
    :description: It's impossible to predict if you'll have time to work on your open source project in the future, but there are ways to minimize the amount of maintenance it requires.
    :url: https://jeffkreeftmeijer.com/open-source-maintainability/
    :image: notifications.png

    If your open source project gains popularity, it will stay included in other
    people's projects and workflows for years. It's impossible to predict if you'll
    have time to maintain your work in the future, but there are ways to minimize
    the amount of maintenance your project requires to remain useful.

    ## Don't add or merge features you won't use yourself
    == Don't add or merge features you won't use yourself

    > It didn't take long to add support for another database management
    > system into your background job library. You spent an evening getting it to
    @@ -39,7 +42,7 @@ need to be in your project. This can be difficult if your users are
    requesting a something you don't need, but it'll make your project easier to
    maintain in the long run.

    ## Drop support for old versions of your dependencies
    == Drop support for old versions of your dependencies

    > You wrote a plug-in for your favorite editor that adds some useful
    > functionality. It's a couple of lines, but wrapping it in a plug-in allows you
    @@ -70,7 +73,7 @@ Don't backport new features. Since you have limited resources you want your
    users to switch to new versions as quickly as possible, even if that means
    they'll have to spend time updating their dependencies.

    ## Hand over projects if you can't help anymore
    == Hand over projects if you can't help anymore

    > You maintain an add-on for some kind of test framework, that's specifically
    > suited for a problem you have. Since others have the same problem, your
  6. jeffkreeftmeijer revised this gist Oct 5, 2017. 1 changed file with 1 addition and 0 deletions.
    1 change: 1 addition & 0 deletions index.adoc
    View file
    Original file line number Diff line number Diff line change
    @@ -1,4 +1,5 @@
    # Keeping open source projects maintainable
    Jeff Kreeftmeijer <https://jeffkreeftmeijer.com>
    :description: It's impossible to predict if you'll have time to work on your open source project in the future, but there are ways to minimize the amount of maintenance it requires.

    If your open source project gains popularity, it will stay included in other
  7. jeffkreeftmeijer revised this gist Oct 4, 2017. 2 changed files with 1 addition and 1 deletion.
    1 change: 0 additions & 1 deletion _metadata.yml
    View file
    Original file line number Diff line number Diff line change
    @@ -1,2 +1 @@
    description: It's impossible to predict if you'll have time to work on your open source project in the future, but there are ways to minimize the amount of maintenance it requires.
    image: https://jeffkreeftmeijer.com/open-source-maintainability/notifications.png
    1 change: 1 addition & 0 deletions index.adoc
    View file
    Original file line number Diff line number Diff line change
    @@ -1,4 +1,5 @@
    # Keeping open source projects maintainable
    :description: It's impossible to predict if you'll have time to work on your open source project in the future, but there are ways to minimize the amount of maintenance it requires.

    If your open source project gains popularity, it will stay included in other
    people's projects and workflows for years. It's impossible to predict if you'll
  8. jeffkreeftmeijer renamed this gist Oct 4, 2017. 1 changed file with 0 additions and 0 deletions.
    0 index.md → index.adoc
    View file
    File renamed without changes.
  9. jeffkreeftmeijer revised this gist Oct 1, 2017. 1 changed file with 2 additions and 0 deletions.
    2 changes: 2 additions & 0 deletions _metadata.yml
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,2 @@
    description: It's impossible to predict if you'll have time to work on your open source project in the future, but there are ways to minimize the amount of maintenance it requires.
    image: https://jeffkreeftmeijer.com/open-source-maintainability/notifications.png
  10. jeffkreeftmeijer revised this gist Oct 1, 2017. 1 changed file with 25 additions and 26 deletions.
    51 changes: 25 additions & 26 deletions index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,4 +1,4 @@
    # Tips for open source project maintainability
    # Keeping open source projects maintainable

    If your open source project gains popularity, it will stay included in other
    people's projects and workflows for years. It's impossible to predict if you'll
    @@ -7,7 +7,7 @@ the amount of maintenance your project requires to remain useful.

    ## Don't add or merge features you won't use yourself

    > It didn't take long to implement support for another database management
    > It didn't take long to add support for another database management
    > system into your background job library. You spent an evening getting it to
    > work, and fifteen minutes here and there to fix some issues in the weeks
    > after releasing it. You don't use that database yourself, but you have some
    @@ -16,14 +16,14 @@ the amount of maintenance your project requires to remain useful.
    >
    > After a while, an issue comes up. Everything works for the database you use,
    > but it's affecting the one you added later. You don't have a lot of time or
    > motivation to fix it and setting up the database takes a while. Ths issue sits
    > motivation to fix it and setting up the database takes a while. The issue sits
    > there for a couple of weeks until somebody else sends a pull request. You
    > understand most of the fix, the code looks okay and you're glad the bug is
    > solved, so you merge it in.
    >
    > When another issue comes in months later, you have a bigger problem than
    > before. You still don't have a lot of time to work on it, and you have code in
    > your project you didn't really understand back when you merged it in. Let
    > your project you didn't completely understand back when you merged it in. Let
    > alone now.
    Instead of merging new features or implementing them yourself, allow for easy
    @@ -32,59 +32,58 @@ that's easy to swap out for something else. If somebody needs your library to
    run on MongoDB, for example, they can write an adapter themselves.

    Don't be afraid to tell contributors to maintain their fork instead of merging
    their pull request. If a feature doesn't help your own use case, it doesn't have
    to be included in your project. This can be difficult if your users are
    their pull request. If a feature doesn't help your own use case, it doesn't
    need to be in your project. This can be difficult if your users are
    requesting a something you don't need, but it'll make your project easier to
    maintain in the long run.
    maintain in the long run.

    ## Drop support for old versions of your dependencies

    > You wrote a plugin for your favorite editor that adds some useful
    > functionality. It's a couple of lines, but wrapping it in a plugin allows you
    > and others to easily install it.
    > You wrote a plug-in for your favorite editor that adds some useful
    > functionality. It's a couple of lines, but wrapping it in a plug-in allows you
    > and others to install it using a plug-in manager.
    >
    > A new version of the editor comes out, which adds some functionality that
    > makes your plugin even more useful. You update it to take advantage of that
    > makes your plug-in even more useful. You update it to take advantage of that
    > new feature and made sure not to break backward compatibility. It has a
    > version check that loads the original implementation when running in an older
    > version of the editor.
    >
    > Since the plugin is just a few lines of code, you barely need to update it.
    > After a couple of years, you'd like to change the plugin to add a new feature
    >
    > After a couple of years, you'd like to change the plug-in to add a new feature
    > or handle some use case better. When you open the code, you can't find a way
    > to get this new feature working for the older versions of the editor.
    >
    >
    > You're not sure if your changes will break anything, and you don't have the
    > ancient editor version running on your machine. Although your project is quite
    > ancient editor version running on your machine. Although your project is
    > popular, you don't know if anyone is still using the old version of the
    > editor.
    Whenever you start using a new version of a dependency, consider dropping
    support for older versions and bumping your major version number. If your users
    are tied to a previous version of your dependency, they should lock to an older
    version of your project. Dropping backward compatibility allows you to remove
    conditional code that's difficult to develop on.
    conditional code that's difficult to develop on.

    Don't backport new features. Since you have limited resources you want your
    users to switch to new versions as quickly as possible, even if that means
    they'll have to spend time updating their dependencies.
    they'll have to spend time updating their dependencies.

    ## Hand over projects if you can't help anymore

    > You maintain an add-on for some kind of test framework, that’s specifically
    > You maintain an add-on for some kind of test framework, that's specifically
    > suited for a problem you have. Since others have the same problem, your
    > project is used by hundreds of people. You haven’t implemented anything you
    > don’t use yourself, and you quickly drop support for old versions of the test
    > project is used by hundreds of people. You haven't implemented anything you
    > don't use yourself, and you quickly drop support for old versions of the test
    > framework.
    >
    > After a while, you start using another test framework on a daily basis. Maybe
    > because a new project at your job uses it, or your new situation doesn’t have
    > because a new project at your job uses it, or your new situation doesn't have
    > that problem your add-on fixed. You stop using your add-on.
    >
    > Your project still provides value for its users, but you don’t have time to
    > reproduce issues you haven’t run into yourself. There’s a handful of people
    > that are excited about your project, so you usually receive a pull request
    > when anything breaks.
    > Your project still provides value for its users, but you don't have time to
    > reproduce issues you haven't run into yourself. There's a handful of people
    > excited about your project, so you usually receive a pull request when
    > something breaks.
    >
    > After merging pull requests for a while, the code starts to lack structure
    > because there's nobody actively maintaining the project. The code becomes
  11. jeffkreeftmeijer revised this gist Sep 17, 2017. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,4 +1,4 @@
    # An open source maintainability manifesto
    # Tips for open source project maintainability

    If your open source project gains popularity, it will stay included in other
    people's projects and workflows for years. It's impossible to predict if you'll
  12. jeffkreeftmeijer revised this gist Sep 17, 2017. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -9,7 +9,7 @@ the amount of maintenance your project requires to remain useful.

    > It didn't take long to implement support for another database management
    > system into your background job library. You spent an evening getting it to
    > work, and fifteen minutes here and there in to fix some issues in the weeks
    > work, and fifteen minutes here and there to fix some issues in the weeks
    > after releasing it. You don't use that database yourself, but you have some
    > users who do, and it doesn't take long to get it set up when somebody reports
    > a bug.
    @@ -84,7 +84,7 @@ they'll have to spend time updating their dependencies.
    > Your project still provides value for its users, but you don’t have time to
    > reproduce issues you haven’t run into yourself. There’s a handful of people
    > that are excited about your project, so you usually receive a pull request
    > when somethin breaks.
    > when anything breaks.
    >
    > After merging pull requests for a while, the code starts to lack structure
    > because there's nobody actively maintaining the project. The code becomes
  13. jeffkreeftmeijer revised this gist Sep 17, 2017. 1 changed file with 0 additions and 0 deletions.
    Binary file added notifications.png
    View file
    Loading
    Sorry, something went wrong. Reload?
    Sorry, we cannot display this file.
    Sorry, this file is invalid so it cannot be displayed.
  14. jeffkreeftmeijer revised this gist Sep 14, 2017. 1 changed file with 56 additions and 57 deletions.
    113 changes: 56 additions & 57 deletions index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,5 +1,10 @@
    # An open source maintainability manifesto

    If your open source project gains popularity, it will stay included in other
    people's projects and workflows for years. It's impossible to predict if you'll
    have time to maintain your work in the future, but there are ways to minimize
    the amount of maintenance your project requires to remain useful.

    ## Don't add or merge features you won't use yourself

    > It didn't take long to implement support for another database management
    @@ -9,23 +14,28 @@
    > users who do, and it doesn't take long to get it set up when somebody reports
    > a bug.
    >
    > After a couple of months, an issue comes up. Everything works for the database
    > you use. It's only affecting the one you added later. You don't have a lot of
    > time or motivation to fix it, so it sits there for a couple of weeks until
    > somebody else sends a pull request. You understand most of the fix, the code
    > looks okay, and you're glad the bug is solved, so you merge it in.
    > After a while, an issue comes up. Everything works for the database you use,
    > but it's affecting the one you added later. You don't have a lot of time or
    > motivation to fix it and setting up the database takes a while. Ths issue sits
    > there for a couple of weeks until somebody else sends a pull request. You
    > understand most of the fix, the code looks okay and you're glad the bug is
    > solved, so you merge it in.
    >
    > When another issue comes in later, you have another problem. It takes a while
    > to get the database set up, you don't have a lot of time to work on it, it
    > doesn't affect the database you use, and you have code in your project you
    > didn't really understand back when you merged it in. Let alone now.
    > When another issue comes in months later, you have a bigger problem than
    > before. You still don't have a lot of time to work on it, and you have code in
    > your project you didn't really understand back when you merged it in. Let
    > alone now.
    Instead of merging new features or implementing them yourself, allow for easy
    extension. Consider separating your project's database layer into an adapter
    that's easy to swap out for something else. If somebody needs your library to
    run on MongoDB, for example, they can write an adapter themselves.

    Instead of implementing the feature yourself, allow for easy extension. If your
    library deals with databases, separate your database concern into an adapter
    that's easily swapped out for something else. Then, if your users need a MongoDB
    adapter, they can implement and maintain it themselves. Don't be afraid to tell
    contributors to maintain their fork of your project instead of merging their
    pull requests to make sure your project remains maintainable in the long run.
    Don't be afraid to tell contributors to maintain their fork instead of merging
    their pull request. If a feature doesn't help your own use case, it doesn't have
    to be included in your project. This can be difficult if your users are
    requesting a something you don't need, but it'll make your project easier to
    maintain in the long run.

    ## Drop support for old versions of your dependencies

    @@ -34,31 +44,32 @@ pull requests to make sure your project remains maintainable in the long run.
    > and others to easily install it.
    >
    > A new version of the editor comes out, which adds some functionality that
    > makes your plugin even more useful. You updated it to take advantage of that
    > makes your plugin even more useful. You update it to take advantage of that
    > new feature and made sure not to break backward compatibility. It has a
    > version check that loads the original implementation when running in an older
    > version of the editor.
    >
    > You use the plugin every day, but since it's just a few lines of code, you
    > barely update it. You simply don't have to.
    >
    >
    > Since the plugin is just a few lines of code, you barely need to update it.
    > After a couple of years, you'd like to change the plugin to add a new feature
    > or handle some use-case better. When you open the code, you can't find a way
    > or handle some use case better. When you open the code, you can't find a way
    > to get this new feature working for the older versions of the editor.
    >
    >
    > You're not sure if your changes will break anything, and you don't have the
    > ancient editor version running on your machine. Although your project is quite
    > popular, you don't know if anyone is still using the old version of the
    > editor.
    Whenever you add a feature that requires a certain version of one of your
    project's dependencies, drop support for old versions of the dependency, and
    bump your project's major version number. Anyone still using the older version
    of the dependency can drop down to the previous version of your project. If you
    need to --and you have time to do so-- you can always backport new features to
    your older versions.
    Whenever you start using a new version of a dependency, consider dropping
    support for older versions and bumping your major version number. If your users
    are tied to a previous version of your dependency, they should lock to an older
    version of your project. Dropping backward compatibility allows you to remove
    conditional code that's difficult to develop on.

    ## Hand over projects to others when you can't help anymore
    Don't backport new features. Since you have limited resources you want your
    users to switch to new versions as quickly as possible, even if that means
    they'll have to spend time updating their dependencies.

    ## Hand over projects if you can't help anymore

    > You maintain an add-on for some kind of test framework, that’s specifically
    > suited for a problem you have. Since others have the same problem, your
    @@ -68,36 +79,24 @@ your older versions.
    >
    > After a while, you start using another test framework on a daily basis. Maybe
    > because a new project at your job uses it, or your new situation doesn’t have
    > that problem your add-on fixed. You stop using your project.
    > that problem your add-on fixed. You stop using your add-on.
    >
    > Your project still provides value for its users, but you don’t have time to
    > reproduce issues you haven’t run into yourself. Luckily, there’s a handful of
    > people that are excited about your project. When something pops up, you’ll
    > usually receive a pull request. Sometimes it takes a while to get to the pull
    > requests. Weeks, even.
    > reproduce issues you haven’t run into yourself. There’s a handful of people
    > that are excited about your project, so you usually receive a pull request
    > when somethin breaks.
    >
    > The code is starting to lack structure because there's nobody actively
    > maintaining the project, increasing technical debt and making it even more
    > difficult to review those pull requests.
    Although you might be the one that started the project, if you don't use it
    yourself, you're not fit to maintain it anymore. If you can't find the time to
    properly review pull requests and keep the code clean, you're hurting the
    project more than you're helping. Either find somebody else who can, or put a
    message in the README explaining the project is unmaintained. Unsubscribe from
    the project's issue tracker, or disable it altogether.

    ## Limited resources

    If it gains popularity, your library will stay included in your users' projects
    or workflows for years. Open source software deals with limited resources by
    definition. You can't predict whether or not you'll have time to work on the
    project years from now, but you can try to make sure maintaining it is as little
    work as possible.
    > After merging pull requests for a while, the code starts to lack structure
    > because there's nobody actively maintaining the project. The code becomes
    > increasingly difficult to understand, and it's becoming difficult to even
    > press the merge button without breaking the build.
    Keep your projects simple and focused on the problem they're trying to solve.
    Never add or keep anything because somebody else needs it. If they do, let them
    build it themselves.
    If you stop using your own project, you're not fit to maintain it anymore. You
    don't have to do all the work, but you need to be among the first to know when
    something breaks. If you don't, you're hurting the project more than you're
    helping.

    You're not obligated to maintain your work forever. If you can't help anymore
    for whatever reason, walk away.
    Hand the project over to somebody that actively uses your project and knows the
    code. If you can't, open an issue in your tracker to announce you're looking for
    a new maintainer. Explain that you can't help anymore and mention that you won't
    be answering issues or reviewing pull requests.
  15. jeffkreeftmeijer revised this gist Sep 14, 2017. 1 changed file with 76 additions and 18 deletions.
    94 changes: 76 additions & 18 deletions index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -2,44 +2,102 @@

    ## Don't add or merge features you won't use yourself

    > It didn't take long to implement support for another database management system into your background job library. You spent an evening getting it to work, and fifteen minutes here and there in to fix some issues in the weeks after releasing it. You don't use that database yourself, but you have some users who do, and it doesn't take long to get it set up when somebody reports a bug.
    > It didn't take long to implement support for another database management
    > system into your background job library. You spent an evening getting it to
    > work, and fifteen minutes here and there in to fix some issues in the weeks
    > after releasing it. You don't use that database yourself, but you have some
    > users who do, and it doesn't take long to get it set up when somebody reports
    > a bug.
    >
    > After a couple of months, an issue comes up. Everything works for the database you use. It's only affecting the one you added later. You don't have a lot of time or motivation to fix it, so it sits there for a couple of weeks until somebody else sends a pull request. You understand most of the fix, the code looks okay, and you're glad the bug is solved, so you merge it in.
    > After a couple of months, an issue comes up. Everything works for the database
    > you use. It's only affecting the one you added later. You don't have a lot of
    > time or motivation to fix it, so it sits there for a couple of weeks until
    > somebody else sends a pull request. You understand most of the fix, the code
    > looks okay, and you're glad the bug is solved, so you merge it in.
    >
    > When another issue comes in later, you have another problem. It takes a while to get the database set up, you don't have a lot of time to work on it, it doesn't affect the database you use, and you have code in your project you didn't really understand back when you merged it in. Let alone now.
    > When another issue comes in later, you have another problem. It takes a while
    > to get the database set up, you don't have a lot of time to work on it, it
    > doesn't affect the database you use, and you have code in your project you
    > didn't really understand back when you merged it in. Let alone now.
    Instead of implementing the feature yourself, allow for easy extension. If your library deals with databases, separate your database concern into an adapter that's easily swapped out for something else. Then, if your users need a MongoDB adapter, they can implement and maintain it themselves. Don't be afraid to tell contributors to maintain their fork of your project instead of merging their pull requests to make sure your project remains maintainable in the long run.
    Instead of implementing the feature yourself, allow for easy extension. If your
    library deals with databases, separate your database concern into an adapter
    that's easily swapped out for something else. Then, if your users need a MongoDB
    adapter, they can implement and maintain it themselves. Don't be afraid to tell
    contributors to maintain their fork of your project instead of merging their
    pull requests to make sure your project remains maintainable in the long run.

    ## Drop support for old versions of your dependencies

    > You wrote a plugin for your favorite editor that adds some useful functionality. It's a couple of lines, but wrapping it in a plugin allows you and others to easily install it.
    > You wrote a plugin for your favorite editor that adds some useful
    > functionality. It's a couple of lines, but wrapping it in a plugin allows you
    > and others to easily install it.
    >
    > A new version of the editor comes out, which adds some functionality that makes your plugin even more useful. You updated it to take advantage of that new feature and made sure not to break backward compatibility. It has a version check that loads the original implementation when running in an older version of the editor.
    > A new version of the editor comes out, which adds some functionality that
    > makes your plugin even more useful. You updated it to take advantage of that
    > new feature and made sure not to break backward compatibility. It has a
    > version check that loads the original implementation when running in an older
    > version of the editor.
    >
    > You use the plugin every day, but since it's just a few lines of code, you barely update it. You simply don't have to.
    > You use the plugin every day, but since it's just a few lines of code, you
    > barely update it. You simply don't have to.
    >
    > After a couple of years, you'd like to change the plugin to add a new feature or handle some use-case better. When you open the code, you can't find a way to get this new feature working for the older versions of the editor.
    > After a couple of years, you'd like to change the plugin to add a new feature
    > or handle some use-case better. When you open the code, you can't find a way
    > to get this new feature working for the older versions of the editor.
    >
    > You're not sure if your changes will break anything, and you don't have the ancient editor version running on your machine. Although your project is quite popular, you don't know if anyone is still using the old version of the editor.
    > You're not sure if your changes will break anything, and you don't have the
    > ancient editor version running on your machine. Although your project is quite
    > popular, you don't know if anyone is still using the old version of the
    > editor.
    Whenever you add a feature that requires a certain version of one of your project's dependencies, drop support for old versions of the dependency, and bump your project's major version number. Anyone still using the older version of the dependency can drop down to the previous version of your project. If you need to --and you have time to do so-- you can always backport new features to your older versions.
    Whenever you add a feature that requires a certain version of one of your
    project's dependencies, drop support for old versions of the dependency, and
    bump your project's major version number. Anyone still using the older version
    of the dependency can drop down to the previous version of your project. If you
    need to --and you have time to do so-- you can always backport new features to
    your older versions.

    ## Hand over projects to others when you can't help anymore

    > You maintain an add-on for some kind of test framework, that’s specifically suited for a problem you have. Since others have the same problem, your project is used by hundreds of people. You haven’t implemented anything you don’t use yourself, and you quickly drop support for old versions of the test framework.
    > You maintain an add-on for some kind of test framework, that’s specifically
    > suited for a problem you have. Since others have the same problem, your
    > project is used by hundreds of people. You haven’t implemented anything you
    > don’t use yourself, and you quickly drop support for old versions of the test
    > framework.
    >
    > After a while, you start using another test framework on a daily basis. Maybe because a new project at your job uses it, or your new situation doesn’t have that problem your add-on fixed. You stop using your project.
    > After a while, you start using another test framework on a daily basis. Maybe
    > because a new project at your job uses it, or your new situation doesn’t have
    > that problem your add-on fixed. You stop using your project.
    >
    > Your project still provides value for its users, but you don’t have time to reproduce issues you haven’t run into yourself. Luckily, there’s a handful of people that are excited about your project. When something pops up, you’ll usually receive a pull request. Sometimes it takes a while to get to the pull requests. Weeks, even.
    > Your project still provides value for its users, but you don’t have time to
    > reproduce issues you haven’t run into yourself. Luckily, there’s a handful of
    > people that are excited about your project. When something pops up, you’ll
    > usually receive a pull request. Sometimes it takes a while to get to the pull
    > requests. Weeks, even.
    >
    > The code is starting to lack structure because there's nobody actively maintaining the project, increasing technical debt and making it even more difficult to review those pull requests.
    > The code is starting to lack structure because there's nobody actively
    > maintaining the project, increasing technical debt and making it even more
    > difficult to review those pull requests.
    Although you might be the one that started the project, if you don't use it yourself, you're not fit to maintain it anymore. If you can't find the time to properly review pull requests and keep the code clean, you're hurting the project more than you're helping. Either find somebody else who can, or put a message in the README explaining the project is unmaintained. Unsubscribe from the project's issue tracker, or disable it altogether.
    Although you might be the one that started the project, if you don't use it
    yourself, you're not fit to maintain it anymore. If you can't find the time to
    properly review pull requests and keep the code clean, you're hurting the
    project more than you're helping. Either find somebody else who can, or put a
    message in the README explaining the project is unmaintained. Unsubscribe from
    the project's issue tracker, or disable it altogether.

    ## Limited resources

    If it gains popularity, your library will stay included in your users' projects or workflows for years. Open source software deals with limited resources by definition. You can't predict whether or not you'll have time to work on the project years from now, but you can try to make sure maintaining it is as little work as possible.
    If it gains popularity, your library will stay included in your users' projects
    or workflows for years. Open source software deals with limited resources by
    definition. You can't predict whether or not you'll have time to work on the
    project years from now, but you can try to make sure maintaining it is as little
    work as possible.

    Keep your projects simple and focused on the problem they're trying to solve. Never add or keep anything because somebody else needs it. If they do, let them build it themselves.
    Keep your projects simple and focused on the problem they're trying to solve.
    Never add or keep anything because somebody else needs it. If they do, let them
    build it themselves.

    You're not obligated to maintain your work forever. If you can't help anymore for whatever reason, walk away.
    You're not obligated to maintain your work forever. If you can't help anymore
    for whatever reason, walk away.
  16. jeffkreeftmeijer revised this gist Sep 10, 2017. 1 changed file with 8 additions and 0 deletions.
    8 changes: 8 additions & 0 deletions index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -35,3 +35,11 @@ Whenever you add a feature that requires a certain version of one of your projec
    > The code is starting to lack structure because there's nobody actively maintaining the project, increasing technical debt and making it even more difficult to review those pull requests.
    Although you might be the one that started the project, if you don't use it yourself, you're not fit to maintain it anymore. If you can't find the time to properly review pull requests and keep the code clean, you're hurting the project more than you're helping. Either find somebody else who can, or put a message in the README explaining the project is unmaintained. Unsubscribe from the project's issue tracker, or disable it altogether.

    ## Limited resources

    If it gains popularity, your library will stay included in your users' projects or workflows for years. Open source software deals with limited resources by definition. You can't predict whether or not you'll have time to work on the project years from now, but you can try to make sure maintaining it is as little work as possible.

    Keep your projects simple and focused on the problem they're trying to solve. Never add or keep anything because somebody else needs it. If they do, let them build it themselves.

    You're not obligated to maintain your work forever. If you can't help anymore for whatever reason, walk away.
  17. jeffkreeftmeijer revised this gist Sep 10, 2017. 1 changed file with 4 additions and 4 deletions.
    8 changes: 4 additions & 4 deletions index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -6,15 +6,15 @@
    >
    > After a couple of months, an issue comes up. Everything works for the database you use. It's only affecting the one you added later. You don't have a lot of time or motivation to fix it, so it sits there for a couple of weeks until somebody else sends a pull request. You understand most of the fix, the code looks okay, and you're glad the bug is solved, so you merge it in.
    >
    > When another issue comes in later, you have even more problems. It takes a while to get the database set up, you don't have a lot of time to work on it, it doesn't affect the database you use, and you have code in your project you didn't really understand back when you merged it in. Let alone now.
    > When another issue comes in later, you have another problem. It takes a while to get the database set up, you don't have a lot of time to work on it, it doesn't affect the database you use, and you have code in your project you didn't really understand back when you merged it in. Let alone now.
    Instead of implementing the feature yourself, allow for easy extension. If your library deals with databases, separate your database concern into an adapter that's easily swapped out for something else. Then, if your users need a MongoDB adapter, they can implement and maintain it themselves. Don't be afraid to tell contributors to maintain their fork of your project instead of merging their pull requests to make sure your project remains maintainable in the long run.

    ## Drop support for old versions of your dependencies

    > You wrote a plugin for your favorite editor that adds some useful functionality. It's a couple of lines, but wrapping it in a plugin allows you and others to easily install it.
    >
    > It's been around for a couple of years, and a new version of the editor added some functionality that makes your plugin even more useful. You updated it to take advantage of that new feature and made sure not to break backward compatibility. It has a version check that loads the original implementation when running in an older version of the editor.
    > A new version of the editor comes out, which adds some functionality that makes your plugin even more useful. You updated it to take advantage of that new feature and made sure not to break backward compatibility. It has a version check that loads the original implementation when running in an older version of the editor.
    >
    > You use the plugin every day, but since it's just a few lines of code, you barely update it. You simply don't have to.
    >
    @@ -30,8 +30,8 @@ Whenever you add a feature that requires a certain version of one of your projec
    >
    > After a while, you start using another test framework on a daily basis. Maybe because a new project at your job uses it, or your new situation doesn’t have that problem your add-on fixed. You stop using your project.
    >
    > Your project still provides value for its users, but you don’t have time to reproduce issues you haven’t run into yourself. Luckily, there’s a handful of people that are excited about your project. When something pops up, you’ll usually receive a pull request. You review the code and merge it if it looks good and if it’s well tested.
    > Your project still provides value for its users, but you don’t have time to reproduce issues you haven’t run into yourself. Luckily, there’s a handful of people that are excited about your project. When something pops up, you’ll usually receive a pull request. Sometimes it takes a while to get to the pull requests. Weeks, even.
    >
    > Sometimes it takes a while to get to the pull requests. Weeks, even. The code is starting to lack structure because there's nobody actively maintaining the project, increasing technical debt and making it even more difficult to review those pull requests.
    > The code is starting to lack structure because there's nobody actively maintaining the project, increasing technical debt and making it even more difficult to review those pull requests.
    Although you might be the one that started the project, if you don't use it yourself, you're not fit to maintain it anymore. If you can't find the time to properly review pull requests and keep the code clean, you're hurting the project more than you're helping. Either find somebody else who can, or put a message in the README explaining the project is unmaintained. Unsubscribe from the project's issue tracker, or disable it altogether.
  18. jeffkreeftmeijer revised this gist Sep 10, 2017. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,6 +1,6 @@
    # An open source maintainability manifesto

    ## Don't merge features you won't use yourself
    ## Don't add or merge features you won't use yourself

    > It didn't take long to implement support for another database management system into your background job library. You spent an evening getting it to work, and fifteen minutes here and there in to fix some issues in the weeks after releasing it. You don't use that database yourself, but you have some users who do, and it doesn't take long to get it set up when somebody reports a bug.
    >
  19. jeffkreeftmeijer revised this gist Sep 10, 2017. 1 changed file with 3 additions and 7 deletions.
    10 changes: 3 additions & 7 deletions index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -8,9 +8,7 @@
    >
    > When another issue comes in later, you have even more problems. It takes a while to get the database set up, you don't have a lot of time to work on it, it doesn't affect the database you use, and you have code in your project you didn't really understand back when you merged it in. Let alone now.
    Instead of implementing the feature yourself, allow for easy extension. If your library deals with databases, separate your database concern into an adapter that's easily swapped out for something else. Then, if your users need a MongoDB adapter, they can implement and maintain it themselves.

    Don't be afraid to tell contributors to maintain their fork of your project instead of merging their pull requests, to make sure your project remains maintainable in the long run.
    Instead of implementing the feature yourself, allow for easy extension. If your library deals with databases, separate your database concern into an adapter that's easily swapped out for something else. Then, if your users need a MongoDB adapter, they can implement and maintain it themselves. Don't be afraid to tell contributors to maintain their fork of your project instead of merging their pull requests to make sure your project remains maintainable in the long run.

    ## Drop support for old versions of your dependencies

    @@ -24,9 +22,7 @@ Don't be afraid to tell contributors to maintain their fork of your project inst
    >
    > You're not sure if your changes will break anything, and you don't have the ancient editor version running on your machine. Although your project is quite popular, you don't know if anyone is still using the old version of the editor.
    Whenever you add a feature that requires a certain version of one of your project's dependencies, drop support for old versions of the dependency, and bump your project's major version number.

    Anyone still using the older version of the dependency can drop down to a lower version of your project. If you need to --and you have time to do so-- you can always backport new features to your older versions.
    Whenever you add a feature that requires a certain version of one of your project's dependencies, drop support for old versions of the dependency, and bump your project's major version number. Anyone still using the older version of the dependency can drop down to the previous version of your project. If you need to --and you have time to do so-- you can always backport new features to your older versions.

    ## Hand over projects to others when you can't help anymore

    @@ -38,4 +34,4 @@ Anyone still using the older version of the dependency can drop down to a lower
    >
    > Sometimes it takes a while to get to the pull requests. Weeks, even. The code is starting to lack structure because there's nobody actively maintaining the project, increasing technical debt and making it even more difficult to review those pull requests.
    Although you might be the one that started the project, if you don't use it yourself, you're not fit to maintain it anymore. If you can't find the time to properly review pull requests and keep the code clean, you're hurting the project more than you're helping. Either find somebody else who is, or put a message in the README explaining the project is unmaintained. Unsubscribe from the project's issue tracker, or disable it altogether.
    Although you might be the one that started the project, if you don't use it yourself, you're not fit to maintain it anymore. If you can't find the time to properly review pull requests and keep the code clean, you're hurting the project more than you're helping. Either find somebody else who can, or put a message in the README explaining the project is unmaintained. Unsubscribe from the project's issue tracker, or disable it altogether.
  20. jeffkreeftmeijer revised this gist Sep 10, 2017. 1 changed file with 24 additions and 10 deletions.
    34 changes: 24 additions & 10 deletions index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -3,25 +3,39 @@
    ## Don't merge features you won't use yourself

    > It didn't take long to implement support for another database management system into your background job library. You spent an evening getting it to work, and fifteen minutes here and there in to fix some issues in the weeks after releasing it. You don't use that database yourself, but you have some users who do, and it doesn't take long to get it set up when somebody reports a bug.
    >
    > After a couple of months, an issue comes up. Everything works for the database you use. It's only affecting the one you added later. You don't have a lot of time or motivation to fix it, so it sits there for a couple of weeks until somebody else sends a pull request. You understand most of the fix, the code looks okay, and you're glad the bug is solved, so you merge it in.
    >
    > When another issue comes in later, you have even more problems. It takes a while to get the database set up, you don't have a lot of time to work on it, it doesn't affect the database you use, and you have code in your project you didn't really understand back when you merged it in. Let alone now.
    Instead of implementing the feature yourself, allow for easy extension. If your library deals with databases, separate your database concern into an adapter that's easily swapped out for something else. Then, if your users need a MongoDB adapter, they can implement and maintain it themselves.

    ## Drop support for old versions of your dependencies
    Don't be afraid to tell contributors to maintain their fork of your project instead of merging their pull requests, to make sure your project remains maintainable in the long run.

    Whenever you add a feature that requires a certain version of one of your project's dependencies, drop support for old versions of the dependency, and bump your project's major version number. If you need to, backport new features to your previous version, but keep your dependencies strict in both.
    ## Drop support for old versions of your dependencies

    ## Hand over projects to others when you can't help anymore
    > You wrote a plugin for your favorite editor that adds some useful functionality. It's a couple of lines, but wrapping it in a plugin allows you and others to easily install it.
    >
    > It's been around for a couple of years, and a new version of the editor added some functionality that makes your plugin even more useful. You updated it to take advantage of that new feature and made sure not to break backward compatibility. It has a version check that loads the original implementation when running in an older version of the editor.
    >
    > You use the plugin every day, but since it's just a few lines of code, you barely update it. You simply don't have to.
    >
    > After a couple of years, you'd like to change the plugin to add a new feature or handle some use-case better. When you open the code, you can't find a way to get this new feature working for the older versions of the editor.
    >
    > You're not sure if your changes will break anything, and you don't have the ancient editor version running on your machine. Although your project is quite popular, you don't know if anyone is still using the old version of the editor.
    You maintain an add-on for some kind of test framework, that's specifically suited for a problem you have. Since others have the same problem, your project is used by hundreds of people. You haven't implemented anything you don't use yourself, and you quickly drop support for old versions of the test framework.
    Whenever you add a feature that requires a certain version of one of your project's dependencies, drop support for old versions of the dependency, and bump your project's major version number.

    After a while, you start using another test framework on a daily basis. Maybe because a new project at your job uses it, or you changed your beliefs about software testing. Maybe your new situation doesn't have that problem your add-on fixed, or you can't convince your colleagues to add it to the dependencies of the project you're working on. You stop using it.
    Anyone still using the older version of the dependency can drop down to a lower version of your project. If you need to --and you have time to do so-- you can always backport new features to your older versions.

    Your project still provides value for its users, but you don't have time to reproduce issues you haven't run into. Luckily, there's a handful of people that are excited about your project, and scour the issues list looking for things they can help out with. When something pops up, you'll usually receive a pull request. You review the code and merge it if it looks good and if it's well tested.
    ## Hand over projects to others when you can't help anymore

    Sometimes merging those pull requests take a while. A couple of days, maybe a week or two.
    > You maintain an add-on for some kind of test framework, that’s specifically suited for a problem you have. Since others have the same problem, your project is used by hundreds of people. You haven’t implemented anything you don’t use yourself, and you quickly drop support for old versions of the test framework.
    >
    > After a while, you start using another test framework on a daily basis. Maybe because a new project at your job uses it, or your new situation doesn’t have that problem your add-on fixed. You stop using your project.
    >
    > Your project still provides value for its users, but you don’t have time to reproduce issues you haven’t run into yourself. Luckily, there’s a handful of people that are excited about your project. When something pops up, you’ll usually receive a pull request. You review the code and merge it if it looks good and if it’s well tested.
    >
    > Sometimes it takes a while to get to the pull requests. Weeks, even. The code is starting to lack structure because there's nobody actively maintaining the project, increasing technical debt and making it even more difficult to review those pull requests.
    Although you might be the one that started the project, if you don't use it yourself, you're not fit to maintain it anymore. Either find somebody else who is, or put a message in the README and disable issues in the project's Github repository.
    Although you might be the one that started the project, if you don't use it yourself, you're not fit to maintain it anymore. If you can't find the time to properly review pull requests and keep the code clean, you're hurting the project more than you're helping. Either find somebody else who is, or put a message in the README explaining the project is unmaintained. Unsubscribe from the project's issue tracker, or disable it altogether.
  21. jeffkreeftmeijer revised this gist Sep 10, 2017. 1 changed file with 3 additions and 3 deletions.
    6 changes: 3 additions & 3 deletions index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -2,11 +2,11 @@

    ## Don't merge features you won't use yourself

    It was quite easy to add a backend for another database management system in your background job library. You installed the database on your machine and spent an hour or two getting your library to work with it. It's thoroughly tested, and the tests are running on CI, so you'll know when something breaks.
    > It didn't take long to implement support for another database management system into your background job library. You spent an evening getting it to work, and fifteen minutes here and there in to fix some issues in the weeks after releasing it. You don't use that database yourself, but you have some users who do, and it doesn't take long to get it set up when somebody reports a bug.
    Your library's users have been asking for support for this database for a while, and they're excited to try it out. You get a few bug reports in the first weeks, but those are all fixed in about half an hour, using the test project you set up.
    > After a couple of months, an issue comes up. Everything works for the database you use. It's only affecting the one you added later. You don't have a lot of time or motivation to fix it, so it sits there for a couple of weeks until somebody else sends a pull request. You understand most of the fix, the code looks okay, and you're glad the bug is solved, so you merge it in.
    After a while, one of your users reports some kind of bug in your library, and you can't reproduce it until they tell you it's breaking on that database you added. It's quite obscure, and you don't have much time, so the report is neglected for a couple of weeks.
    > When another issue comes in later, you have even more problems. It takes a while to get the database set up, you don't have a lot of time to work on it, it doesn't affect the database you use, and you have code in your project you didn't really understand back when you merged it in. Let alone now.
    Instead of implementing the feature yourself, allow for easy extension. If your library deals with databases, separate your database concern into an adapter that's easily swapped out for something else. Then, if your users need a MongoDB adapter, they can implement and maintain it themselves.

  22. jeffkreeftmeijer revised this gist Sep 10, 2017. 1 changed file with 11 additions and 7 deletions.
    18 changes: 11 additions & 7 deletions index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -2,22 +2,26 @@

    ## Don't merge features you won't use yourself

    It might be tempting to write a backend for another database [TODO], or add support for another operating system. These days, it's not a lot of work to install MySQL, or run a VM to with Linux to test on. You'll get them set up, and you implement the feature in an hour or two. Of course, you'll test it thoroughly, and even add it to your CI build so you'll know when it breaks in the future.
    It was quite easy to add a backend for another database management system in your background job library. You installed the database on your machine and spent an hour or two getting your library to work with it. It's thoroughly tested, and the tests are running on CI, so you'll know when something breaks.

    After getting requests to implement support for this for a while, you're finally able to ship this new feature to your users. It's picked up quickly, and you'll get a few bug reports in the next couple of weeks. When that happens, you'll find a couple of spare minutes to spin up your test setup. You fix the issues and you'll add tests for them.
    Your library's users have been asking for support for this database for a while, and they're excited to try it out. You get a few bug reports in the first weeks, but those are all fixed in about half an hour, using the test project you set up.

    A couple of months later, a new version of that dependency comes out. You only notice because somebody was kind enough to send you a pull request. After reading up on the new version, updating your test setup, and reviewing the code, you merge it.
    After a while, one of your users reports some kind of bug in your library, and you can't reproduce it until they tell you it's breaking on that database you added. It's quite obscure, and you don't have much time, so the report is neglected for a couple of weeks.

    An issue is created in your project's issue tracker, and you upgrade your test setup to that new version. You spend an evening to add support for it.
    Instead of implementing the feature yourself, allow for easy extension. If your library deals with databases, separate your database concern into an adapter that's easily swapped out for something else. Then, if your users need a MongoDB adapter, they can implement and maintain it themselves.

    ## Drop support for old versions of your dependencies


    Whenever you add a feature that requires a certain version of one of your project's dependencies, drop support for old versions of the dependency, and bump your project's major version number. If you need to, backport new features to your previous version, but keep your dependencies strict in both.

    ## Hand over projects to others when you can't help anymore

    You maintain an add-on for some kind of test framework, that's specifically suited for a problem you have. Since others have the same problem, your project is used by hundreds of people. You haven't implemented anything you don't use yourself, and you quickly drop support for old versions of the test framework.

    After a while, you start using another test framework on a daily basis. Maybe because a new project at your job uses it, or you changed your beliefs about software testing. Maybe your new situation doesn't have that problem your add-on fixed, or you can't convince your colleagues to add it to the dependencies of the project you're working on. You stop using the add-on.
    After a while, you start using another test framework on a daily basis. Maybe because a new project at your job uses it, or you changed your beliefs about software testing. Maybe your new situation doesn't have that problem your add-on fixed, or you can't convince your colleagues to add it to the dependencies of the project you're working on. You stop using it.

    Your project still provides value for its users, but you don't have time to reproduce issues you haven't run into. Luckily, there's a handful of people that are excited about your project, and scour the issues list looking for things they can help out with. When something pops up, you'll usually receive a pull request. You review the code and merge it if it looks good and if it's well tested.

    Sometimes merging those pull requests take a while. A couple of days, maybe a week or two.

    Your project still provides value for its users, but you don't have time to reproduce issues you haven't run into. Luckily, there's a handful of people that are excited about your project, and scour the issues list looking for things they can help out with. When something pops up, you'll usually receive a pull request. You review the code, and merge it if it looks good and if it's well tested.
    Although you might be the one that started the project, if you don't use it yourself, you're not fit to maintain it anymore. Either find somebody else who is, or put a message in the README and disable issues in the project's Github repository.
  23. jeffkreeftmeijer created this gist Sep 3, 2017.
    23 changes: 23 additions & 0 deletions index.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,23 @@
    # An open source maintainability manifesto

    ## Don't merge features you won't use yourself

    It might be tempting to write a backend for another database [TODO], or add support for another operating system. These days, it's not a lot of work to install MySQL, or run a VM to with Linux to test on. You'll get them set up, and you implement the feature in an hour or two. Of course, you'll test it thoroughly, and even add it to your CI build so you'll know when it breaks in the future.

    After getting requests to implement support for this for a while, you're finally able to ship this new feature to your users. It's picked up quickly, and you'll get a few bug reports in the next couple of weeks. When that happens, you'll find a couple of spare minutes to spin up your test setup. You fix the issues and you'll add tests for them.

    A couple of months later, a new version of that dependency comes out. You only notice because somebody was kind enough to send you a pull request. After reading up on the new version, updating your test setup, and reviewing the code, you merge it.

    An issue is created in your project's issue tracker, and you upgrade your test setup to that new version. You spend an evening to add support for it.

    ## Drop support for old versions of your dependencies



    ## Hand over projects to others when you can't help anymore

    You maintain an add-on for some kind of test framework, that's specifically suited for a problem you have. Since others have the same problem, your project is used by hundreds of people. You haven't implemented anything you don't use yourself, and you quickly drop support for old versions of the test framework.

    After a while, you start using another test framework on a daily basis. Maybe because a new project at your job uses it, or you changed your beliefs about software testing. Maybe your new situation doesn't have that problem your add-on fixed, or you can't convince your colleagues to add it to the dependencies of the project you're working on. You stop using the add-on.

    Your project still provides value for its users, but you don't have time to reproduce issues you haven't run into. Luckily, there's a handful of people that are excited about your project, and scour the issues list looking for things they can help out with. When something pops up, you'll usually receive a pull request. You review the code, and merge it if it looks good and if it's well tested.