How to improve docs related to contributing?

Those are all valid points.

I agree that the technical documentation about the OS internals, useful only to the developers, doesn’t need to (shouldn’t ?) be at the same place than more general documentation pertaining to the end user or the non-programming contributor.

I also think that using the main website is the best way to expose said documentation to new members of the community.

And of course we should not move a page or document without putting in place some kind of redirection.

Hi @PulkoMandy and @xipehuz,

Yes, I think it’s a good idea to go with that, having contributions-related information on the main site, and more specific development documentation in a new place.

Do we still have the source code for that?

That is something we definitely need to look at - thank you for pointing that out! Not too sure how we’re going to set up redirects, though - it sounds like a big task.

Regarding redirects we specifically use Netlify to host our Hugo site because it supports redirects. Here is the file for the website to see the format: https://github.com/haiku/website/blob/master/static/_redirects

Speaking of Netlify we are currently paying them $45 per month because we needed to handle the higher traffic due to the Beta 2 release and needed to upgrade to the Pro plan. This is pretty exorbitant given we only spend around $120 for the rest of our infrastructure. So if anyone wants to explore options for this that would help. I do think we could restructure our account by dropping users to get it down to $19 a month when they change their billing in January. Or maybe we can drop back to the free plan. I really haven’t had a chance to look at it.

1 Like

I was going to check for alternatives but thought to check Netlify’s website for an open-source program (since we are a FOSS project, we can get benefits).

And good news, they do have such a program! It provides the same features as the Pro plan, with added bonuses such as free hosting and unlimited users. This way, we can save money but not worry about having to lose any hosting capabilities. However, some changes (mostly to our website) will be needed to ensure we’re in accordance with the program:

  • 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.

More information is available here: Open Source Plan Policy | Netlify
The above link also provides information on how to apply (via a web form).

In terms of licensing, most of Haiku is under the MIT license which means we’re good to go.

We need a code of conduct though, and after searching through the Github repo and the main site I haven’t found anything resembling one.

In terms of the links, we can just put a link in the footer (using one of the premade badges), or if people don’t like it, just on the bottom of the main page (it does say we can either have it on our main page OR all internal pages).

AFAIK Haiku doesnt have any currently (or called differently), this should be discussed first.

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):
https://www.contributor-covenant.org/

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: https://www.haiku-os.org/community/organization/policies/

2 Likes

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.

3 Likes

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:
https://opensource-form.netlify.com/

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.

3 Likes

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.