shamelessly based on the Contributing to Open Source on Github guide.
A great way to get involved in ESN is to contribute to the existing IT projects you have proably seen being used (Satellite, Event Registration System etc.). There are projects for every skill set. This guide will cover what you might find in a typical project and how to make a great contribution.
Find Projects
We recommend that you start by finding a project that you’re already (or are interested in) using. Here are a few great places to look:
Tip for Beginners: When viewing issues, search by the "Novice" label. This way you can limit the results to the easier ones to start with.
A Typical Project
Below are some elements you’re likely to come across in an IT project on ESNgit.
The Team
All projects have a team from the IT Committee that is maintaining and/or developing the project in different roles:
- Project Leader/Master is the one who is in charge of the project and also responsible for its planning and implementation
- Developers are the users primarily doing the work on a project and driving the direction. Oftentimes the owner and the maintainer are the same. They have write access to the repository.
- Reporters are the users who often use and care about the project and are active in discussions for features or issues. Many times they are also responsible for the documentationo of the project.
The Docs
The what’s-what of common files in projects.
Readme
Nearly all ESN IT projects include a README.md file. The readme provides a lay of the land for a project with details on how to use, build and sometimes contribute to a project.
Documentation and Wikis
Many larger projects go beyond a readme to give instructions for how people can use their project. In such cases you should check the "Wiki" tab (far right position in the repository's page) for more information.
Contributing to a Project
Now that you’ve found the material for understanding the project, here is how you can take action.
Create an Issue
If you find a bug in a project you’re using (and you don’t know how to fix it), have trouble following the documentation or have a question about the project – create an issue! There’s nothing to it and whatever issue you’re having, you’re likely not the only one, so others will find your issue helpful, too. For more information on how issues work, check out Github's Issues guide.
Issues Pro Tips
- Check existing issues for your issue. Duplicating an issue is slower for both parties so search through open and closed issues to see if what you’re running into has been addressed already.
- Be clear about what your problem is: what was the expected outcome, what happened instead? Detail how someone else can recreate the problem.
- Link to demos recreating the problem on things like JSFiddle or CodePen.
- Include system details like what the browser, library or operating system you’re using and its version.
- Paste error output or logs in your issue or in a Snippet. If pasting them in the issue, wrap it in three backticks:
` `so that it renders nicely.
Merge Request
If you’re able to patch the bug or add the feature yourself – fantastic, make a merge request with the code! Once you’ve submitted a merge request the maintainer(s) can compare your branch to the existing one and decide whether or not to incorporate (merge) your changes.
Merge Request Pro Tips
- Fork the repository and clone it locally. Connect your local to the original ‘upstream’ repository by adding it as a remote. Pull in changes from ‘upstream’ often so that you stay up to date so that when you submit your merge request, merge conflicts will be less likely. See more detailed instructions in the Syncying a fork guide.
- Create a branch for your edits. As we're encouraging the usage of the Gitflow Workflow, we recommend using the respective naming convention (i.e. #-title-of-issue).
- Be clear about what problem is occurring and how someone can recreate that problem or why your feature will help. Then be equally as clear about the steps you took to make your changes.
- It’s best to test. Run your changes against any existing tests if they exist and create new ones when needed. Whether tests exist or not, make sure your changes don’t break the existing project.
- Include screenshots of the before and after if your changes include differences in HTML/CSS. Drag and drop the images into the body of your pull request.
- Contribute in the style of the project to the best of your abilities. This may mean using indents, semi colons or comments differently than you would in your own repository, but makes it easier for the maintainer to merge, others to understand and maintain in the future.
Open Merge Requests
Once you’ve opened a merge request a discussion will start around your proposed changes. Other contributors and users may chime in, but ultimately the decision is made by the maintainer(s). You may be asked to make some changes to your merge request, if so, add more commits to your branch and push them – they’ll automatically go into the existing merge request.
If your merge request is merged – great! If it is not, no sweat, it may not be what the project maintainer had in mind, or they were already working on it. This happens, so our recommendation is to take any feedback you’ve received and go forth and merge request again – or create your own open source project.