New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Requesting documentation (hello world) for development #8287

Closed
vfseanm opened this Issue Sep 25, 2017 · 15 comments

Comments

Projects
None yet
@vfseanm

vfseanm commented Sep 25, 2017

I'm new to Rocket Chat, and really wish there was documentation on how you develop and test the system day-to-day. E.g:

  • How do you build and what changes require a rebuild? (meteor build is very slow, and I don't see documentation on how to use it for Rocket Chat).
  • Is there any building necessary for mongo DB? Is there a test DB?
  • How do you run tests (I only see one documented)?

I'm basically wishing there were a hello world development guide. Having trouble getting started and I'm sure others are too. Thanks!

@ms10398

This comment has been minimized.

Show comment
Hide comment
@ms10398

ms10398 Oct 5, 2017

I would like to work on it
How should I start Can anyone guide me as this is a new project to me.

ms10398 commented Oct 5, 2017

I would like to work on it
How should I start Can anyone guide me as this is a new project to me.

@ohadleshno

This comment has been minimized.

Show comment
Hide comment
@ohadleshno

ohadleshno Oct 5, 2017

I would like to work on it too.

ohadleshno commented Oct 5, 2017

I would like to work on it too.

@MrBunBuns

This comment has been minimized.

Show comment
Hide comment
@MrBunBuns

MrBunBuns Oct 5, 2017

Me and my team are working on Rocket.Chat for our school project and would like to help you since we experienced the same difficulty when we first started. Just let us know if you would like us to and we will get started for you right away!

MrBunBuns commented Oct 5, 2017

Me and my team are working on Rocket.Chat for our school project and would like to help you since we experienced the same difficulty when we first started. Just let us know if you would like us to and we will get started for you right away!

@abhishek71994

This comment has been minimized.

Show comment
Hide comment
@abhishek71994

abhishek71994 Oct 9, 2017

I would like to contribute as well. This would help me get up and running in making Open Source Contributions.

abhishek71994 commented Oct 9, 2017

I would like to contribute as well. This would help me get up and running in making Open Source Contributions.

@alanbuxey

This comment has been minimized.

Show comment
Hide comment
@alanbuxey

alanbuxey Oct 10, 2017

okay - so the first point of call would be to create a list of requirements that are not already covered (or need improving) on the official pages

https://rocket.chat/docs

are the docs required for admins of the system, developers or end users of the system ?

alanbuxey commented Oct 10, 2017

okay - so the first point of call would be to create a list of requirements that are not already covered (or need improving) on the official pages

https://rocket.chat/docs

are the docs required for admins of the system, developers or end users of the system ?

@abhishek71994

This comment has been minimized.

Show comment
Hide comment
@abhishek71994

abhishek71994 Oct 10, 2017

So basically replicate the list in the Rocket.chat docs?

abhishek71994 commented Oct 10, 2017

So basically replicate the list in the Rocket.chat docs?

@Deathrow77

This comment has been minimized.

Show comment
Hide comment
@Deathrow77

Deathrow77 Oct 11, 2017

I would like to work on this project too.

Deathrow77 commented Oct 11, 2017

I would like to work on this project too.

@vfseanm

This comment has been minimized.

Show comment
Hide comment
@vfseanm

vfseanm Oct 12, 2017

What's missing:
So the docs on contributing and developing don't give any instructions on how to begin - it just says "You can find Rocket.Chat repositories here. If you see some issue you are willing to work on, just comment on it."

An example of what would help developers get started:

  • Here's how you fork Rocket Chat.
  • Here's how you pull and deploy your fork locally (commands). With warning that the build is super slow and links to what to do if it breaks.
  • Add the words "Hello World" somewhere visible on the home page.
  • Here's how you push the change to your forked github repo.
  • Here's how you submit a Pull Request and what to expect.

The page can also include some beginner material like I mentioned initially:

  • What changes require a rebuild?
  • Is there any building necessary for mongo DB? Is there a test DB?
  • How do you run tests?

vfseanm commented Oct 12, 2017

What's missing:
So the docs on contributing and developing don't give any instructions on how to begin - it just says "You can find Rocket.Chat repositories here. If you see some issue you are willing to work on, just comment on it."

An example of what would help developers get started:

  • Here's how you fork Rocket Chat.
  • Here's how you pull and deploy your fork locally (commands). With warning that the build is super slow and links to what to do if it breaks.
  • Add the words "Hello World" somewhere visible on the home page.
  • Here's how you push the change to your forked github repo.
  • Here's how you submit a Pull Request and what to expect.

The page can also include some beginner material like I mentioned initially:

  • What changes require a rebuild?
  • Is there any building necessary for mongo DB? Is there a test DB?
  • How do you run tests?
@JSzaszvari

This comment has been minimized.

Show comment
Hide comment
@JSzaszvari

JSzaszvari Oct 21, 2017

Member

Pre-Warning: I'm not a Rocket.Chat Staff member, just a community contributor. Nothing in this post should be taken as coming from the Rocket.Chat team.

Alright, Pre-Apologies to anyone annoyed by this post. Not in a great mood tonight and ended up ranting:

This doesn't appear to actually be a problem with Rocket.Chat but a misunderstanding of some basics and other technologies that arnt necessarily specific to Rocket.Chat

The first observation that I've made here is that there is a expectation for the Rocket.Chat staff to teach you how to use the underlying technologies that it's built with. So far I've seen

  • Questions that are essentially "How do I use git"
  • How do I use MongoDB
  • How do I make a change too/rebuild a MeteorJS project

Now I dont mean to pick on anyone, Just trying to encourage people and show them that there are better places out there to be asking these questions. I'll address some specific posts here - Once again, not trying to put down or pick on anyone, just trying to get a better understanding of whats being asked. So I'll answer the questions in a blunt and quick fashion.

@vfseanm

how you fork Rocket Chat.

The exact same way you fork the other 26 million projects on GitHub. If you go to https://guides.github.com/ you'll find a main topic called "Forking Projects - Ever find a project on GitHub that you want to work on? Find out how you can contribute with Forking." - https://guides.github.com/activities/forking/

On that same page is also subtopics "Making and pushing changes" and "Making a Pull Request"

Here's how you pull and deploy your fork locally (commands).

See my comment above.

Here's how you push the change to your forked github repo.

Same answer again.

Here's how you submit a Pull Request and what to expect.

And again, all covered in every Git 101 Getting Started Guide on the internet.

In the rare case that they follow a different process for PR's, whats the worst that can happen by simply trying? I would submit the PR and if something needs to be done differently or didnt follow correct procedure, the Repository Maintainers/People who look at the PR's are usually more than happy to give you a helping hand on how you can get your change into the project.

With warning that the build is super slow and links to what to do if it breaks.
What changes require a rebuild?
Is there any building necessary for mongo DB? Is there a test DB?

If you are contributing to a project as large as this one for example, In my opinion there would be a certain level of assumed knowledge about the underlying technologies that it uses. What i'm getting at here is that none of the 3 issues raised above strike me as issues with Rocket.Chat or the Project, but a lack of knowledge with MeteorJS.

All of those questions can be answered on this single page in the MeteorJS docs - https://docs.meteor.com/commandline.html

With warning that the build is super slow and links to what to do if it breaks.

Any MeteorJS project this large is going to take a long time to build. This isnt a RC issue at all. There's millions of things that could break, The issue could be with your build environment, a mistake you made when making a change, etc etc. But there is no issue that I have yet to come across where you copy and paste the error into google, and 50x solutions come up all over StackOverflow and GitHub.

What changes require a rebuild?

As per the MeteorJS docs. Pretty much every single change that you make to a package that you want reflected on the front end needs a rebuild.

Is there any building necessary for mongo DB? Is there a test DB?

This functionality is built into the MeteorJS build/run process as per the documentation I just linked.

This is the same across the board, for any project that uses Meteor. See the commands on the page I linked above: "meteor run", "meteor mongo", "meteor build", "meteor npm"

All of the above knowledge is transferrable between any Meteor project hosted on GitHub.

You said:

So the docs on contributing and developing don't give any instructions on how to begin - it just says "You can find Rocket.Chat repositories here. If you see some issue you are willing to work on, just comment on it."

Well... Yes? That is what it says, It's not usually a case of "First we will teach you how to use git, then we will teach you Meteor basics" - It really is a case of "Here is 'Project X' - We use A, B and C as underlying technologies/the platform is built on those. Feel free to contribute anything back" - It's not their job to ensure you have a basic understanding of the tech that it's built with, as they are delivering a software package built off that stuff, not a 101 into using git and 101 programming course or teaching people how to manage meteor applications.

You said this too:

I'm basically wishing there were a hello world development guide.

Well it's your lucky day, Because there is thousands of them.

Just google "Git 101", or "Building a meteorJS project" and there is a wealth of knowledge out there.

The specifics on contributing to this project and the workflow are all really well documented here - https://docs.rocket.chat/developer-guides/branches-and-releases/

Testing is covered here - https://docs.rocket.chat/developer-guides/testing/

The reason why i complain like this is that the Rocket.Chat team are using standards based technologies where the knowledge is transferrable between any project that uses similar tooling.

And the main point I am trying to make here is that the Rocket.Chat team can either:

A) Teach people the basics of using Git, Using Meteor and Contributing back, which would leave little time do to actual work on the project
or
B) They can focus on improving RocketChat, Delivering more features, Fixing Bugs, and just generally being awesome at what they do.

I strongly feel it's not their job to waste time on documenting this stuff considering there is so so so so much great documentation on this out there already, and it would be a huge waste of time rehashing it for this particular project, as theres nothing special about the way RocketChat works.

If you are looking for the "exact commands" that need to be run, then there is no better documentation than a script with the actual build process thats sitting in the root of the repository here: https://github.com/RocketChat/Rocket.Chat/blob/develop/example-build-run.sh

Go follow a few MeteorJS tutorials out there on the web, Follow some online git tutorials/walkthroughs then I guarantee, before you know it, you'll feel like a expert when jumping into a project like this - You'll be confident and excited that you can make a impact.

It's unfair on the Rocket.Chat team to be expected to take time out of working on the 2000 issue tickets on github to write documentation on how to use GitHub, or use MeteorJS on a basic level, because that already exists out there.

Before I started playing with Rocket.Chat I had never written a line of JavaScript in my life, Never used MongoDB and had never even seen MeteorJS - And Here I am 1 year later with a Custom RocketChat deployment approaching nearly 40,000 lines of custom code for my particular use case.

Another good way of figuring this stuff out is to just search all over github for RocketChat. As in look at what other people are doing in their own repos/what stuff they are contributing by searching across all repos like this: https://github.com/search?utf8=%E2%9C%93&q=RocketChat&type=

That right now brings up 341 repository results of people who have developed their own tools/plugins/whatever for RocketChat and you'll get a better idea of how it all works.

Anyways. I'll stop now.

Good luck on your journey mate.

Member

JSzaszvari commented Oct 21, 2017

Pre-Warning: I'm not a Rocket.Chat Staff member, just a community contributor. Nothing in this post should be taken as coming from the Rocket.Chat team.

Alright, Pre-Apologies to anyone annoyed by this post. Not in a great mood tonight and ended up ranting:

This doesn't appear to actually be a problem with Rocket.Chat but a misunderstanding of some basics and other technologies that arnt necessarily specific to Rocket.Chat

The first observation that I've made here is that there is a expectation for the Rocket.Chat staff to teach you how to use the underlying technologies that it's built with. So far I've seen

  • Questions that are essentially "How do I use git"
  • How do I use MongoDB
  • How do I make a change too/rebuild a MeteorJS project

Now I dont mean to pick on anyone, Just trying to encourage people and show them that there are better places out there to be asking these questions. I'll address some specific posts here - Once again, not trying to put down or pick on anyone, just trying to get a better understanding of whats being asked. So I'll answer the questions in a blunt and quick fashion.

@vfseanm

how you fork Rocket Chat.

The exact same way you fork the other 26 million projects on GitHub. If you go to https://guides.github.com/ you'll find a main topic called "Forking Projects - Ever find a project on GitHub that you want to work on? Find out how you can contribute with Forking." - https://guides.github.com/activities/forking/

On that same page is also subtopics "Making and pushing changes" and "Making a Pull Request"

Here's how you pull and deploy your fork locally (commands).

See my comment above.

Here's how you push the change to your forked github repo.

Same answer again.

Here's how you submit a Pull Request and what to expect.

And again, all covered in every Git 101 Getting Started Guide on the internet.

In the rare case that they follow a different process for PR's, whats the worst that can happen by simply trying? I would submit the PR and if something needs to be done differently or didnt follow correct procedure, the Repository Maintainers/People who look at the PR's are usually more than happy to give you a helping hand on how you can get your change into the project.

With warning that the build is super slow and links to what to do if it breaks.
What changes require a rebuild?
Is there any building necessary for mongo DB? Is there a test DB?

If you are contributing to a project as large as this one for example, In my opinion there would be a certain level of assumed knowledge about the underlying technologies that it uses. What i'm getting at here is that none of the 3 issues raised above strike me as issues with Rocket.Chat or the Project, but a lack of knowledge with MeteorJS.

All of those questions can be answered on this single page in the MeteorJS docs - https://docs.meteor.com/commandline.html

With warning that the build is super slow and links to what to do if it breaks.

Any MeteorJS project this large is going to take a long time to build. This isnt a RC issue at all. There's millions of things that could break, The issue could be with your build environment, a mistake you made when making a change, etc etc. But there is no issue that I have yet to come across where you copy and paste the error into google, and 50x solutions come up all over StackOverflow and GitHub.

What changes require a rebuild?

As per the MeteorJS docs. Pretty much every single change that you make to a package that you want reflected on the front end needs a rebuild.

Is there any building necessary for mongo DB? Is there a test DB?

This functionality is built into the MeteorJS build/run process as per the documentation I just linked.

This is the same across the board, for any project that uses Meteor. See the commands on the page I linked above: "meteor run", "meteor mongo", "meteor build", "meteor npm"

All of the above knowledge is transferrable between any Meteor project hosted on GitHub.

You said:

So the docs on contributing and developing don't give any instructions on how to begin - it just says "You can find Rocket.Chat repositories here. If you see some issue you are willing to work on, just comment on it."

Well... Yes? That is what it says, It's not usually a case of "First we will teach you how to use git, then we will teach you Meteor basics" - It really is a case of "Here is 'Project X' - We use A, B and C as underlying technologies/the platform is built on those. Feel free to contribute anything back" - It's not their job to ensure you have a basic understanding of the tech that it's built with, as they are delivering a software package built off that stuff, not a 101 into using git and 101 programming course or teaching people how to manage meteor applications.

You said this too:

I'm basically wishing there were a hello world development guide.

Well it's your lucky day, Because there is thousands of them.

Just google "Git 101", or "Building a meteorJS project" and there is a wealth of knowledge out there.

The specifics on contributing to this project and the workflow are all really well documented here - https://docs.rocket.chat/developer-guides/branches-and-releases/

Testing is covered here - https://docs.rocket.chat/developer-guides/testing/

The reason why i complain like this is that the Rocket.Chat team are using standards based technologies where the knowledge is transferrable between any project that uses similar tooling.

And the main point I am trying to make here is that the Rocket.Chat team can either:

A) Teach people the basics of using Git, Using Meteor and Contributing back, which would leave little time do to actual work on the project
or
B) They can focus on improving RocketChat, Delivering more features, Fixing Bugs, and just generally being awesome at what they do.

I strongly feel it's not their job to waste time on documenting this stuff considering there is so so so so much great documentation on this out there already, and it would be a huge waste of time rehashing it for this particular project, as theres nothing special about the way RocketChat works.

If you are looking for the "exact commands" that need to be run, then there is no better documentation than a script with the actual build process thats sitting in the root of the repository here: https://github.com/RocketChat/Rocket.Chat/blob/develop/example-build-run.sh

Go follow a few MeteorJS tutorials out there on the web, Follow some online git tutorials/walkthroughs then I guarantee, before you know it, you'll feel like a expert when jumping into a project like this - You'll be confident and excited that you can make a impact.

It's unfair on the Rocket.Chat team to be expected to take time out of working on the 2000 issue tickets on github to write documentation on how to use GitHub, or use MeteorJS on a basic level, because that already exists out there.

Before I started playing with Rocket.Chat I had never written a line of JavaScript in my life, Never used MongoDB and had never even seen MeteorJS - And Here I am 1 year later with a Custom RocketChat deployment approaching nearly 40,000 lines of custom code for my particular use case.

Another good way of figuring this stuff out is to just search all over github for RocketChat. As in look at what other people are doing in their own repos/what stuff they are contributing by searching across all repos like this: https://github.com/search?utf8=%E2%9C%93&q=RocketChat&type=

That right now brings up 341 repository results of people who have developed their own tools/plugins/whatever for RocketChat and you'll get a better idea of how it all works.

Anyways. I'll stop now.

Good luck on your journey mate.

@MrBunBuns

This comment has been minimized.

Show comment
Hide comment
@MrBunBuns

MrBunBuns Oct 21, 2017

I've made some changes to the Rocket.Chat.Docs/1. Contributing/Developing/README.md within the Achaikos branch. I added a tutorial for how to get it up and running on linux machines. If anyone could take a look and provide feedback that would be great. Also I want to add a section for windows as well, however I cant get meteor to work in gitbash.

MrBunBuns commented Oct 21, 2017

I've made some changes to the Rocket.Chat.Docs/1. Contributing/Developing/README.md within the Achaikos branch. I added a tutorial for how to get it up and running on linux machines. If anyone could take a look and provide feedback that would be great. Also I want to add a section for windows as well, however I cant get meteor to work in gitbash.

@vfseanm

This comment has been minimized.

Show comment
Hide comment
@vfseanm

vfseanm Oct 22, 2017

@JSzaszvari and anyone else from Rocket Chat - apologies if I stressed anyone out with this issue. I definitely didn't mean anything I suggested as a criticism! What you folks are doing is awesome and it's amazing how much you've documented already.

I thought a handholding guide that helped a novice engineer make a trivial change would help the breadth of those who could contribute to the project. @JSzaszvari, you're right, most of those steps are documented already elsewhere (e.g. by github and meteor) and it could be basically just links to other tutorials, followed by like the name of a file where you can make a visible change. Like "Hey, you're new? Okay, you're gonna want to learn Meteor JS, here's the link to that. Also Mongo DB, here's that link. Also if you don't know how to use github here's that link. Great, now clone the repo and here's a filename where you can make a visible change." Calling out example-build-run.sh as a reference would be helpful too.

Or not, this is obviously crazy low priority. Feel free to close this issue.

vfseanm commented Oct 22, 2017

@JSzaszvari and anyone else from Rocket Chat - apologies if I stressed anyone out with this issue. I definitely didn't mean anything I suggested as a criticism! What you folks are doing is awesome and it's amazing how much you've documented already.

I thought a handholding guide that helped a novice engineer make a trivial change would help the breadth of those who could contribute to the project. @JSzaszvari, you're right, most of those steps are documented already elsewhere (e.g. by github and meteor) and it could be basically just links to other tutorials, followed by like the name of a file where you can make a visible change. Like "Hey, you're new? Okay, you're gonna want to learn Meteor JS, here's the link to that. Also Mongo DB, here's that link. Also if you don't know how to use github here's that link. Great, now clone the repo and here's a filename where you can make a visible change." Calling out example-build-run.sh as a reference would be helpful too.

Or not, this is obviously crazy low priority. Feel free to close this issue.

@vchrombie

This comment has been minimized.

Show comment
Hide comment
@vchrombie

vchrombie Oct 23, 2017

I am also interested to work on this.

vchrombie commented Oct 23, 2017

I am also interested to work on this.

@pixidust724

This comment has been minimized.

Show comment
Hide comment
@pixidust724

pixidust724 Oct 24, 2017

How do get involved in this?

pixidust724 commented Oct 24, 2017

How do get involved in this?

@MrBunBuns

This comment has been minimized.

Show comment
Hide comment
@MrBunBuns

MrBunBuns Oct 30, 2017

I have made improvements to the developing guide for Rocket.Chat.Docs that have improved the guide for how to start development. Also your issues aren't related Rocket.Chat but developing as a whole. As a result I would recommend close this as it isn't really an issue.

MrBunBuns commented Oct 30, 2017

I have made improvements to the developing guide for Rocket.Chat.Docs that have improved the guide for how to start development. Also your issues aren't related Rocket.Chat but developing as a whole. As a result I would recommend close this as it isn't really an issue.

@geekgonecrazy

This comment has been minimized.

Show comment
Hide comment
@geekgonecrazy

geekgonecrazy Feb 16, 2018

Member

We've made a lot of improvements to our docs. Others have also contributed changes to our getting started guide for developers. https://rocket.chat/docs/developer-guides/quick-start/

Please feel free to add improvements: https://github.com/RocketChat/docs

Going to go ahead and close. Feel free to open issues about specific things on our docs repo that you'd like to see documents for, or even contribute them.

Thanks,

Member

geekgonecrazy commented Feb 16, 2018

We've made a lot of improvements to our docs. Others have also contributed changes to our getting started guide for developers. https://rocket.chat/docs/developer-guides/quick-start/

Please feel free to add improvements: https://github.com/RocketChat/docs

Going to go ahead and close. Feel free to open issues about specific things on our docs repo that you'd like to see documents for, or even contribute them.

Thanks,

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment