BookStack Code Mirror - website/blob - content/blog/2022/contributing-to-open-source.md

   1 +++
   2 categories = ["Community"]
   3 tags = ["Open Source"]
   4 title = "Contributing to BookStack (And Open Source)"
   5 date = 2022-02-12T20:00:00Z
   6 author = "Dan Brown"
   7 image = "/images/blog-cover-images/unsplash/lions-joel-herzog.jpg"
   8 slug = "contributing-to-open-source"
   9 draft = false
  10 +++
  11
  12 A few times recently people have asked how they can get involved
  13 and help BookStack so I thought I'd formalize my response into this
  14 blog post. While the below is my view in regards to BookStack contributions, it
  15 will likely apply to many open source projects
  16
  17
  18 #### Contribute Code
  19
  20 This is one of the most direct ways to get involved with an open source project, while
  21 potentially being the most difficult and intimidating. I remember making
  22 my first pull request (PR) to an open source project on GitHub. I put a fair
  23 amount of work in to provide a much requested feature, opened the PR with an
  24 explanation, and there it sat for 6 months before it was closed without comment
  25 or reasoning.
  26
  27 The trouble with contributing code is that every project is different, with a different
  28 process, with different maintainers that have different visions and opinions.
  29 From maintaining BookStack I've come to understand the challenges from a maintainer point of view.
  30 It can feel really bad to reject someone's work, after they've spent time on something, and it can
  31 be time consuming to guide someone through getting their contribution into an acceptable state.
  32
  33 When looking to contribute code to a project, this is the general process I'd advise:
  34
  35 - Look for contributing guidance in the project readme or `contributing.md` file and follow that if existing.
  36 - Check the license of the project to see if it's something you can even contribute to.
  37 - Look over a few existing pull requests in the project, both open and closed, to get a feel for any expected conventions and to understand how the maintainers communicate.
  38 - Search for open and closed issues relating to your planned contribution. It may be that your idea has already been requested but is not something desired by the maintainer. It may be that someone has already started or the idea needs to be fleshed out first.
  39 - If you're going to invest a non-insignificant amount of time in your contribution, and would feel insulted or upset upon a quick rejection, communicate with the project maintainers (via issues, their discussion forum or via a draft PR) early on to understand if you're on the right track for a contribution that would be accepted, as to avoid disappointment down the line.
  40 - Be receptive to feedback and be prepared to follow requests from the maintainer. I've seen some cases where people have struggled with this and taken offence to requested changes, or asked for the maintainer to spend time to justify in detail their requests. Be understanding that the maintainer is likely the one that's going to be primarily responsible for the code going forward. A request for change doesn't by default mean your code is bad, but the maintainer may just forsee other cases that need to be handled based upon experience, or they need things done a certain way to ease maintenance.
  41
  42 #### Provide Translations
  43
  44 If you're skilled with fluency in multiple languages, contributing translation text can be a
  45 massive help. Translations within BookStack help the project be accessible to a much wider
  46 audience. Apart from a memorized French speech about "Family Guy" (Or "Les Griffins") I don't
  47 know much outside of English but luckily a bunch of wonderful folks in our community
  48 keep BookStack translated in, at the time of writing, 36 language variants.
  49
  50 ![BookStack Crowdin Page](/images/2022/02/crowdin.png)
  51
  52 You often don't need to have code skills to help with translating. Sometimes you'll need
  53 to edit text files otherwise it's common for projects to use a platform that provides
  54 an easier-to-use interface. Within BookStack [we use Crowdin as our translation platform of choice](https://crowdin.com/project/bookstack).
  55
  56 #### Help on Issues & Feature Requests
  57
  58 When maintaining a project like BookStack, GitHub issues can consume a large amount of time.
  59 Our own issues list is comprised of:
  60
  61 - Support Requests
  62 - Feature Requests
  63 - Bug Reports
  64
  65 We utilise different entry forms for these different categories to tag up the issues
  66 appropriately and attempt to get the needed information although that's not always provided.
  67
  68 Support requests are probably the easiest to help with if you're familiar with the technologies
  69 and environments where the project may run. Requesting vital or missing details, guiding the issue
  70 creator to the relevant documentation, or providing options & next steps to attempt resolution, are all good first
  71 steps that can help move things forward and save time for the maintainers.
  72
  73 With feature requests, it can be useful to provide perspective and add to the discussion for ideas.
  74 Sometimes it's just a case of showing the issue creator alternative paths to their desired outcome.
  75 It's quite common, especially by more technical users, that feature requests are opened requesting a certain implementation rather than stating their intended benefit purpose.
  76 For example: Requesting "Add a header bar link to page X" instead of "Provide faster access to page X from any location, since this would benefit Y".
  77 A request for a specific implementation can keep you blind to better alternatives to reaching the same outcome. If this occurs, it can be very useful to communicate with the issue creator to understand that actual desire behind their implementation request.
  78 Even if a feature is requested for something that you would not desire, it can be useful to know from a maintainer
  79 perspective if a request is something that would go unused in your environment and hence may only
  80 add as extra complexity/clutter.
  81
  82 Bug reports can be very useful to a maintainer to create a more stable and issue-free platform but
  83 they're not always provided in an ideal format, even when we have measures in place to request certain
  84 details. Upon that, sometimes bug reports are opened for elements that are in reality a matter of opinion or based upon false expectations.
  85 Validating and confirming re-production of issues can be a massive help and speed up the process for someone to get onto fixing the fundamental issue/bug.
  86
  87 Finally, there's general issue management. Reporting issues that are no longer relevant, or advising of potential duplication, can save time and keep the issues list down.
  88
  89 #### Testing and Bug Reporting
  90
  91 Many open source projects don't have the full QA capabilities of commercial offerings.
  92 While I attempt to write automated tests where possible, and manually test each logical
  93 scenario, you can't catch absolutely everything and it's commonplace that I'd be the only
  94 tester for a new feature being released.
  95
  96 Reporting bugs you come across in production can be very useful, just ensure you're running the
  97 latest version (since things may have already been fixed) and provide as much detail as
  98 possible to replicate the bug (Including environment details such as browser used, operating system etc...).
  99
 100 Testing pre-release developments can be valuable to ensure another use-case has been tested
 101 before changes are shipped to production, but communicate with the maintainers before attempting
 102 this since the pre-release environment may be knowingly unstable and you may just end up wasting your own time
 103 in addition to the maintainer's. Probably best to find some recent changes, then reach out to see
 104 if they're ready for testing & feedback.
 105
 106 An alternative form of bug reporting is security issue reporting. Security is of course quite vital
 107 to most projects. It's quite common for services & projects to have security "bug bounties" where you
 108 can be rewarded money for discovering and reporting vulnerabilities.
 109 In BookStack I've dealt with many submissions via [huntr.dev](https://huntr.dev/) which has led to many issues being reported and fixed, with the reporters receiving significant monetary gain for their discovery
 110 without being at cost to us. Upon that they have also rewarded me for patching many of the vulnerabilities found.
 111
 112 ![Huntr.dev example BookStack vulnerability report](/images/2022/02/huntr-dev.png)
 113
 114
 115 If going down the security route, many open source projects will have their own procedures and classifications when it comes to reporting security vulnerabilities. Look within the project readme or for a `security.md` file like [the one we have in BookStack](https://github.com/BookStackApp/BookStack/blob/development/.github/SECURITY.md).
 116
 117 #### Create Guides, Videos, Articles etc...
 118
 119 ![List of BookStack videos by community members](/images/2022/02/community-videos.png)
 120
 121 Text and video media can have a great benefit on a project.
 122 Not only do they help in spreading the word, they can provide
 123 a massive morale boost. Seeing people take the time to create videos about BookStack
 124 creates a great sense of pride to help me continue on the project, while often showcasing
 125 an alternative viewpoint in terms of thoughts and usage of the platform.
 126 Upon their emotional and network affect, this kind of media can just generally help
 127 in terms of providing guidance to new users. Here are two videos as examples:
 128
 129 - ["Install Bookstack on Synology in 2 Minutes" by Geeked](https://youtu.be/_13K1DeZwhk)
 130 - ["BookStack Installed on Docker and Portainer" by DB Tech](https://youtu.be/NhPw1DvxYZc)
 131
 132 Both of these provide very useful visual guidance relating to specific hosting platforms that I
 133 wouldn't cover myself, hence helping improve accessibility to the project for a sizable chunk
 134 of users.
 135
 136 #### Get Involved on Discord
 137
 138 We [have a discord server](https://www.bookstackapp.com/links/discord) to host quick and informal discussion for BookStack.
 139 People often pop in to request support, discuss ideas or talk about ways to do things.
 140 Supporting others and being part of the conversation can help build the sense of community within
 141 the project and help BookStack be something more than just its codebase.
 142
 143 #### Share the Project
 144
 145 Simply sharing the project around can provide a positive affect on a project.
 146 I [use f5bot](https://f5bot.com/) to track BookStack mentions on Reddit & Hacker News,
 147 for which I see multiple almost daily which again can provide a great morale boost.
 148 In addition, links posted to the project is great for SEO, to help us rank up
 149 in search engine results and therefore reach a wider audience.
 150
 151 On thing to be careful of is sharing the project in the incorrect context or over-sharing.
 152 If spam-like behavior is seen then it can cause resentment towards the project.
 153 For this reason I strongly limit how often I personally post the project, as a new submission, on Reddit.
 154
 155 #### Contribute Financially
 156
 157 Financial contributions are used differently depending on the project.
 158 For the majority of BookStack's development I avoided receiving donations to prevent
 159 getting money involved in the project. I then changed my stance with the idea that I
 160 could take donations and redistribute them to the projects we rely upon within BookStack.
 161 Since I decided to take a career break to focus on BookStack I paused any additional
 162 "donation forwarding" and instead have been using them to support myself financially.
 163 However they're used, donations can provide extra options and flexibility to a project or,
 164 at minimum, indicate your support and appreciation for a project.
 165
 166 ![My GitHub Sponsors Profile](/images/2022/02/github-sponsors.png)
 167
 168 [I currently accept donations via GitHub sponsors](https://github.com/sponsors/ssddanbrown/).
 169 Recently, I altered my higher-level tiers to have rewards of [logo display on our website](https://www.bookstackapp.com/#sponsors)
 170 and readme. This was to give something back to our larger sponsors while trying to entice
 171 additional large sponsorships from business that can afford these levels.
 172
 173
 174 ----
 175
 176 <span style="font-size: 0.8em;opacity:0.9;">Header Image Credits: <span>Photo by <a href="https://unsplash.com/@joel_herzog?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Joel Herzog</a> on <a href="https://unsplash.com/s/photos/animal-pack?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></span></span>
 177