How to improve docs related to contributing?

I think we have sort of an unofficial code of conduct. If we create a document I would like to keep it simple and avoid too much troublesome stuff. I know sometimes they are used as a political weapon by some people and I don’t think we want that.

1 Like

Good news - we don’t have to! There is a thing called the “Contributor Covenant” which is a freely reusable Code of Conduct (similar to how we can use the MIT license):

The Contributor Covenant is written especially for FOSS communities and projects so it should do the trick for Haiku.

We already have one even if it’s not called that way:


That’s even better - Netlify requires us to clearly call it a Code of Conduct and link it in the Haiku repositories etc.:

So, if that’s fine with everyone, could someone go about doing that?

In response to @leavengood’s concerns about people misusing the Policies/Code of Conduct, personally, I think the existing one is as simple and as fair as possible and it’s hard for people to turn such a document into a “weapon”.

1 Like

Including a docs/ section would only really appeal to… well, developers, and it splits work across different places. If the website could include the documentation included in the repository and dynamically update it, that would be more than perfect AND future-proof.

3 posts were split to a new topic: Code of conduct / community guidelines

We discussed adopting it at some point in the past and decided against it for a variety of reasons. The “Community Policies” page is our equivalent of a “code of conduct”, and it has served us well enough so far. Perhaps we need to tweak it a bit, but at least I do not think we need to replace it entirely.

Well, we call it “Community Policies”, isn’t that sufficient? If Netlify does not care what is in the document, only that it is called a “Code of Conduct”, that would not make much sense.


Yeah, preferably we should just keep it the way it is, but @leavengood asked whether we had any alternatives to hosting because we were paying quite a bit for Netlify hosting.

Netlify has an open-source program which provides free hosting but with the same benefits as our current plan - with some added requirements:

  • Includes a license listed on the Open Source Initiative approved license list or a Creative Commons license that includes “attribution” or places the work in the public domain.
  • Features a Code of Conduct at the top level directory of the project repository or prominently in the documentation (with a link in the navigation, footer, or homepage).
  • Must feature a link to our service on your main page, or all internal pages. You have two options:
  • We have premade badges for your convenience, or
  • You may create your own link, which should read “This site is powered by Netlify”, and include a link back to our home page.

As you can see the second dot point is the reason why we are discussing a Code in the first place. Although, I feel as our Policy page may suffice…

1 Like

For reference, here is the form we have to fill in:

I don’t think Netlify can dictate what our Code of Conduct is, just that we have one. I say we just link to what we have.


I wholeheartedly concur.

Agreed! Do you want to fill it out?

They don’t say it has to be called “Code of conduct”. They just want us to have one.

The one we have is good enough.

1 Like

Agreed - it is fair and simple. No need to change something that works.

Wait - we still need to add in the link to Netlify. Any ideas on where we could put this?

I think I can handle this. You’ve provided a lot of help just doing the research.

I figure we can add the Netlify banner in the footer on the website template, and after I have stuff in place I will fill out that form.

I appreciate the help! Sometimes we just need someone to do the annoying research :wink:


No worries! Always happy to help :smiley:

While we’re at it, Docker also has an open-source program:

So, speaking for myself here, I’d love to help contribute to the documetation if there was an easier way to do so. I tried to make a single line commit previously but dealing with Gerrit got me all confused and I ended up making a mess of it… as some of you may remember. Eventually my change was unneeded, since I was able to archive the docs being referenced into the Haiku website.
Im more than willing to help convert the existing docs that are in the wiki onto the site, but I’d want direction from the Team for how they want it structured before I put in work that has to be redone.

I know from looking around earlier, that some of the docs seem to be written so that they can be generated with DocsyGen, which I’ve never used before and obviously there’s a learning curve there to understand how that works before someone can pitch in and help improve the docs that are generated with that.

This past year I’ve been working as a Validcation and Documentation Engineer for iXsystems (the people behind FreeNAS and TrueNAS, converting from their old sphinx docs system to a new git based hugo docs site) and running their Security Hugo Site. So Im ready to go on anything you guys want to throw at me on that front. If I can avoid having to have a dedicated system for doing commits through the haiku git instance and dealing with gerrit… I’m happy to dive in.

But that of course is all contingent on you guys deciding that you want the docs hosted on the Haiku website and not somewhere else.

It’s you’re project, so its your choice. If I can help, Im happy to do so.


If you don’t want or can’t use Gerrit, you can submit your changes in other ways (attach patches on the bugtracker, send us link to a git repo elsewhere where you have them, etc). Gerrit is a nice tool for code review but if you don’t want to use it.

As for “making a mess”, I already forgot about it. It happens regularly and it’s always possible to fix.

Personally I prefer that changes get on Gerrit (even if not in perfect shape) rather than having to track them in the bugtracker, in git repos all over the place, etc. But, I can adapt myself.

The use of Doxygen is very simple. It is documented here: HOWTO « user « docs - haiku - Haiku's main repository but essentially it’s this:

  • Go to the directory where the “Doxyfile” is (docs/user in our case)
  • Type “doxygen” in a Terminal
  • The HTML files are generated

I don’t understand what you mean by “a dedicated system”. To send patches to Haiku you need to use the git command line tool, that’s all. If you know how to do a git push, you’re all set.

So, in the short term: don’t worry about Gerrit and making a mess on it. We’ll be here to clean things up. Or just put your changes elsewhere and we’ll find a way to integrate them.

1 Like

Whilst we are figuring out what medium to use, I think we can take this opportunity to integrate a proper search function into the main site; which is the only gripe I have with the main site. Currently, it utilises Google search which is not very convenient nor intuitive.

Hugo recommends several open-source and commercial search solutions which can be easily integrated into the main website: