Contribution

[ButuzGOL]

I am interested in your project and want to contribute but it's hard to figure out what I should start maybe start gitter chat ?
Or you can suggest me here ?

[hai-cea]

@ButuzGOL Thanks for suggesting gitter chat. I've set it up here.

As for contributions, we'd love any help. I think it would be helpful if we indicated what's in-progress somewhere. Anyone have suggestions for this?

[lloydcotten]

Maybe trello?

[bradmontgomery]

👍 to trello, which I personally like.

I'll also throw this out as a 2nd suggestion: You've got [https://github.com/callemall/material-ui/wiki](this wiki thing) enabled for the project, too.

[hai-cea]

I just found out about https://huboard.com. Seems like a pretty good tool?

[mairh]

I would suggest to use waffle.io

It has really good integration with github.

[hai-cea]

Anyone else want to weigh in? I can probably set this up in the next week. @jkruder @oliviertassinari @pomerantsev

[pomerantsev]

Isn't Github Issues a good enough tool?

[mairh]

@pomerantsev Both https://huboard.com and https://waffle.io are Kanban board for github issues. Its more easy to visualise the progress on github issues if we use those tools.

[jkruder]

@hai-cea huboard looks pretty slick. I think I'm leaning more towards trying utilize GitHub first like @pomerantsev has suggested. I personally don't like using more tools than you need. We could start by organizing issues as new features/bugs/defects and make use of milestones so that contributors can see what the near term goals are. We can also start assigning issues to individuals so that other contributors know who is working on what.

I haven't had much opportunity to work with GitHub's issue tracking interface. So it may not be very effective and a tool like huboard or waffle makes sense. Whichever way we go, I'm on board with more organization and communication of the direction of the project with all of the contributors.

@hai-cea I'd be happy to help out with managing/facilitating the issues.

[hai-cea]

@pomerantsev @jkruder ok - I think we'll try to better use GitHub issues with milestones, labels, etc before bringing on another tool.

@jkruder Thanks for volunteering to to help with managing the issues. Maybe we should first talk about what labels / milestones we need etc?

[jkruder]

@hai-cea I think that's a good idea. Do you want to discuss that in this thread?

[hai-cea]

@jkruder Here are a couple of my thoughts:

1. We need to find some way to communicate the project roadmap. This should be some kind of living doc since priorities can change based on input from the community. As it stands, here's what I think the current roadmap looks like:
   • v0.10
     • Make components more composable (Embrace DOM-like structure #27, [LeftNav] Make composable #413, [AppBar] Make composable #773). I'm currently working on a revamp of menus. This will address composability for DropDownMenu, SelectField, IconMenu, LeftNav (Navigation Drawer). AppBar and Toolbar needs to be done as well.
   • v0.11
     • Create a Higher Order Component to help set up the app. This component can take care of initializing/overriding themes, injecting tap-event-plugin, media-queries, and more?
     • Address issue with vendor prefixing and server-side rendering.
   • Along the way, I'd love to be able address the accessibility issues of components. (Keyboard and general accessibility #61, [Dialog] does not scope tabbing #156)
2. I'm not sure which labels make sense? Maybe you can suggest some scheme on what you think would be helpful. I guess milestones can tie back to the roadmap?

[jkruder]

1. I agree, I think this will provide much needed insight to the people supporting this library. I think creating milestones is the best way to communicate the vision. I would suggest staying 1-2 milestones ahead of the current milestone so that we all have an idea where MUI will be in the near term.
   • If we can continue to identify high level features/epics we can turn those into milestones. Making components more compossible could be a milestone and we can identify the various components that need work. Accessibility could be another milestone.
   • Along the way we can always issue a 0.9.X milestone if we identify a serious defect.
   • And we can always juggle the order of the milestones if we feel a particular feature is more important/immediately useful.
   • Testing would be a useful feature; I might identify some of the more stable components and test those. Components like the table/card/lists are relatively new and will most likely experience a lot of changes (or maybe that's more reason to test them?).
2. I like the idea of using [Component] in the name of the issue/PR. It makes it clear what the topic is. That way we do not need to create labels for each component; although we could go that route. Bug/Defect, Enhancement, and New Component/Feature are some common labels that will cover most of the issues/PRs. We could also create a label for documentation efforts and priority (useful for bugs/defects). Status would also be useful so that people know which issues have been approved for work, which are currently being worked, which reported defects have been confirmed, etc
3. We should also begin assigning people to issues so that the community knows who is taking ownership of a particular effort. I'm not sure if assigning a user is something we can let the community do or if one of the maintainers (yourself) has to do the assignment.

[mattapperson]

Regarding the above now closed ticket. Unit tests are/need to be a big part of this... for instance, right now master is broken because select box has duplicate prop definition.

[pomerantsev]

@jkruder - good suggestions!
@hai-cea if you take a look at larger projects like react, angular, ember, they're all using some combination of labels, milestones and assignments to make it clearer to people contributing to the project what's going on.
Personally, I don't think that adhering to some principles is an all or nothing decision. You could add structure to the development process incrementally and see which additions prove helpful.

[hai-cea]

Thanks for all the input - love everything you guys are saying.

I believe issues can only be labeled by team members and assigned to team members. We can't make every contributor a team member. Do you guys have any suggestions on this?

[jkruder]

What we could do is require any PR to trace back to one or more Issues (preferably one-to-one so scope creep is not an issue) and someone who is resolving an Issue can "claim" the issue by mentioning the collaborators so that someone can apply the "working" label to the Issue so that anyone else viewing the issue knows that it's currently being worked on. Not the best, but it could work.

Might want to reconsider utilizing waffle/trello if we really want to assign people to tasks and depict the state of MUI. https://waffle.io/ has a demo/preview capability so you could use that and see if you can assign issues to people who are not team members. You can also use this type of tool to control what issues are resolved by putting them in a ready queue. Issues not in the queue can still be worked, but someone on the core MUI team should transition the ticket/authorize it for a particular release.

[hai-cea]

I figured out a way to assign issues to contributors. I think the next step is to come up with some contribution guidelines/process and document them on the main readme and docs site.

After this is done, I think we can close this issue.

[mbrookes]

As well as contribution guidelines, it would be helpful to document (at a high level) the internal structure of the components, how they build up from the various mixins etc., which components depend on what, and general organisation of the code-base.

It would also be nice to see some kind of roadmap - what are the short, medium and long-term goals of the project? What major activities are underway, and which ones are a high priority to tackle next?

[alitaheri]

@mbrookes I'm working on a roadmap #2403. and about Contribution guideline I absolutely agree, many people opening issues ask this question. @oliviertassinari We should address this in 0.14.0

[alitaheri]

@oliviertassinari Do you think we should add a contribution guild in the community section too?

[oliviertassinari]

No, I think that this need a section on his own.

[alitaheri]

You're right. should we put it in the docs? Or just a CONTRIBUTING.md file that github can pickup too?

[oliviertassinari]

A CONTRIBUTING.md than can be used by the docs and referenced in the Readme sounds great.

[alitaheri]

Cool. I'm going to make a PR so we can discuss the contents.

[mbrookes]

@alitaheri - I had some thoughts about this, and have been meaning to put them down somewhere. Feel free to cherry pick, reword, expand, remove as needed. :)

In no particular order, and by no-means definitive:

• Project philosophy
  • Overarching objective of the project
  • What it is / isn't intended to be
  • How we interpret / apply Material Design guidelines
• Directory structure
  • What goes where?
• File (and directory) naming convention
• Code conventions
  • Describe linting rules?
  • Code order
  • General direction (ES6, mixins etc...)
  • Other general conventions
• Anatomy of a component
  • Internal structure of the components
  • How components build up from the various mixins etc.
• Anatomy of the documentation
  • How the docs site works / how to document new components
  • Minimal requirements for documenting new components
• Component dependancies
  • What components depend on what others
  • Document internal components not covered by docs site
• How to build and run
• Testing
• Issue / PR / Review / Merge process (how to successfully get a PR accepted).

[alitaheri]

@mbrookes Good thinking 👍 👍 I guess we need to organize a bit before we can actually include some of these points.

[mbrookes]

Useful content from @alitaheri - #2950 (comment)