contributing.md - share project guidelines for how we work

gerbrent commented 2 years ago

We've been receiving some great questions form folks just starting to join us in this project, and I feel they might be worth collecting at least in the form of an FAQ.

I'm happy to collect them w recommendations from you all.

gerbrent commented 2 years ago

A few items captured here for now:

branch cleanup on PR merges

- https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches
What I do at work is just delete right away after I merge the PR. There’s a button right there on the GitHub interface.

PRs, work in progress

I'd also advise not to be shy about pushing PRs, just mark them as WIP

Issue assignment for work in progress

currently non-organisation members cannot self-assign.

Since I’ve not work with a team using git, is the etiquette to assign a issue to ourselves if we are working on it or just comment on the issue saying we are working on it?

brentgphoto:

the key is to communicate enough to avoid unnecessary duplication of efforts, which has already happened once.

So, if you want to tackle a particular ticket feel free to assign yourself (if that's within your ability). Worst case a comment works too. the important thing is to communicate your intention, and progress so we can help you find success. and, as I've seen already: it seems like when there's momentum on a ticket we all seem to get inspired aswell. Progress is wonderfully contagious!

what to work on?

I'm just cloning the repo and setting stuff up. Is there a particular ticket/ticket set I might be able to help with specifically ? Or just float around unassigned issues?

brentgphoto:

so far we've been operating on the following principle:

collect ideas and features and tasks via tickets

when you feel inspired about a particular ticket or feature, have at it!

if you have a particular skillset, feel free to focus there. I've also been attempting to specifically label "low priority" tasks, but others are so far of fairly equal importance. Anytime there is something clearly urgent, the "urgent" tag will be use.

other than that - have fun!

gerbrent commented 2 years ago

Top priority is to hopefully avoid using anyone's time/effort - including you - on items that may eventually not be used. We want to spend time/effort on things that get implemented! So it's good practice to get consult first on an idea and the greater vision before beginning work to make sure you can implement in the way that ends up best for all the moving pieces.

kbondarev commented 2 years ago

Maybe add that the frontend framework used is bulma and we should strive to use the CSS classes, components, etc. from there when possible rather than making custom CSS solutions

https://bulma.io/documentation/

gerbrent commented 2 years ago

... make it so @kbondarev ! I don't have the technical chops to write that cohesively, so will need to come from someone with more insight.

gerbrent commented 2 years ago

see /CONTRIBUTING.md

(also, any GH shortcodes to reference repo files? )

kbondarev commented 2 years ago

I will do this over the weekend :)

kbondarev commented 2 years ago

@gerbrent Regards to shortcuts for file referencing, I don’t know any. In an issue I’d do the same as you did. But inside markdown files you can use relative paths in the link

kbondarev commented 2 years ago

I will do this over the weekend :) @gerbrent

Ended up putting this one to the last on my list today and it's a little too late now. This will be the next thing I'll tackle.

kbondarev commented 2 years ago

@gerbrent see #127 (sometimes I feel like I'm sending a Wuphf when I reference the issue in the PR and the PR in the issue)

Direct link to the new doc file

I cleaned up the doc a little. Kept the same Q&A format, but removed the quotes and made some bullet point answers instead. I think it a little more visually appealing and easier to follow.
Added some emojis (wimpy kinda made me realizes that emojis make things a little more colorful :laughing: )
Added a couple more questions and answers

What do you think? Is it good, anything missing I should add?

gerbrent commented 2 years ago

a little more visually appealing and easier to follow.

👍🏻

Added some emojis (wimpy kinda made me realizes that emojis make things a little more colorful laughing )

I'm just going to place this here.... https://gitmoji.dev/

Regarding the Q & A format - that was born out of pure laziness, haste, and conversation capture, but if we feel it's a nice approachable format I'm all for it.

gerbrent commented 2 years ago

Feedback on the content and layout changes:

Dear @kbondarev - I think I love you. SUUUUUPER amazing additions and editing. Way better than I was envisioning/could have done myself. We are better for having you here!

JupiterBroadcasting / jupiterbroadcasting.com