Slim down some of documentation and generally update based on current
thoughts and naming.
This commit is contained in:
Mike McQuaid 2017-03-10 09:50:45 +00:00
Родитель 73454edcf6
Коммит 43e7aa4f35
3 изменённых файлов: 13 добавлений и 63 удалений

Просмотреть файл

@ -1,14 +1,12 @@
# Contributing to OSS Friday # Contributing to Open Source Friday
Want to contribute to OSS Friday? That's great! Here are a couple of guidelines that will help you contribute. Before we get started: Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md) to ensure that this project is a welcoming place for **everyone** to contribute to. By participating in this project you agree to abide by its terms. Want to contribute to Open Source Friday? That's great! Here are a couple of guidelines that will help you contribute. Before we get started: Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md) to ensure that this project is a welcoming place for **everyone** to contribute to. By participating in this project you agree to abide by its terms.
#### Overview #### Overview
* [Contribution workflow](#contribution-workflow) * [Contribution workflow](#contribution-workflow)
* [Setup instructions](#setup-instructions) * [Setup instructions](#setup-instructions)
* [Reporting a bug](#reporting-a-bug) * [Reporting a bug](#reporting-a-bug)
* [Contributing to an existing issue](#contributing-to-an-existing-issue)
* [Our labels](#our-labels)
* [Additional info](#additional-info) * [Additional info](#additional-info)
## Contribution workflow ## Contribution workflow
@ -32,44 +30,7 @@ So you've found a bug, and want to help us fix it? Before filing a bug report, p
If you want to be really thorough, there is a great overview on Stack Overflow of [what you should consider when reporting a bug](http://stackoverflow.com/questions/240323/how-to-report-bugs-the-smart-way). If you want to be really thorough, there is a great overview on Stack Overflow of [what you should consider when reporting a bug](http://stackoverflow.com/questions/240323/how-to-report-bugs-the-smart-way).
It goes without saying that you're welcome to help investigate further and/or find a fix for the bug. If you want to do so, just mention it in your bug report and offer your help! It goes without saying that you're welcome to help investigate further and/or find a fix for the bug. If you want to do so, just mention it in your bug report and offer your help!
## Contributing to an existing issue
### Finding an issue to work on
We've got a few open issues and are always glad to get help on that front. You can view the list of issues [here](https://github.com/librariesio/libraries.io/issues). Most of the issues are labelled, so you can use the labels to get an idea of which issue could be a good fit for you. (Here's [a good article](https://medium.freecodecamp.com/finding-your-first-open-source-project-or-bug-to-work-on-1712f651e5ba) on how to find your first bug to fix).
Before getting to work, take a look at the issue and at the conversation around it. Has someone already offered to work on the issue? Has someone been assigned to the issue? If so, you might want to check with them to see whether they're still actively working on it.
If the issue is a few months old, it might be a good idea to write a short comment to double-check that the issue or feature is still a valid one to jump on.
Feel free to ask for more detail on what is expected: are there any more details or specifications you need to know?
And if at any point you get stuck: don't hesitate to ask for help.
### Making your contribution
We've outlined the contribution workflow [here](#contribution-workflow). If you're a first-timer, don't worry! GitHub has a ton of guides to help you through your first pull request: You can find out more about pull requests [here](https://help.github.com/articles/about-pull-requests/) and about creating a pull request [here](https://help.github.com/articles/creating-a-pull-request/).
## Our labels
- **On Hold**: We will generally mark an issue as blocked if it requires more context for us to fix, is waiting on an updated version of a library that the issue depends on, or is waiting on a maintainer to do something before it can be answered. There may be other conditions in which we'll mark an issue as blocked, and we'll make this clear in the issue comments.
- **bug**: An issue gets marked as a bug if (surprise!) the issue is linked to a bug in our code or something broken in our infrastructure. Bugs are usually the highest priority kind of issue as they will affect our users.
- **bugsnag**: If an issue or exception in production code has been flagged via Bugsnag, it is labelled with this automatically.
- **documentation**: If an issue requires changes or clarification to our documentation (READMEs, wiki, code comments, etc.) then it will be marked with this issue. These issues normally do not pertain to code changes and are ideal for those who don't necessarily want to get their hands dirty with code.
- **duplicate**: If an issue has been reported before, it will be marked with this label. This flags that a previous issue may not have been fixed as expected, or in the case of things we don't intend to fix or issues currently in discussion in another open issue, it means that we are likely to close the issue.
- **enhancement**: These are improvements to the codebase that are "nice to have", and are usually medium to high impact but low importance. This includes improvements to features that already exist and may be assigned a milestone to give you an idea as to when it might be implemented. These are great for contributors that might have some extra spare time on their hands and would prefer to change existing code rather than add large chunks of brand new code.
- **feature**: An issue will be marked with this label if it adds a new, discrete functional element to the codebase. They will generally require large amounts or effort to implement, require changes to both front-end view templates and back-end code, and assume prior knowledge of the codebase, making these the most tricky kinds of issues to close. However, they can be the most rewarding to close for the intrepid!
- **help wanted**: Issues will be marked with this label by the maintainers if we'd like outside contributors to pitch in with code or opinions before we close them. These do not assume any skill level and are great opportunities for all members of our community to steer the direction of the project.
- **invalid**: These are rare, and normally have been submitted in error.
- **needs rebase**: You will find this label normally attached to pull requests, and means that the maintainers would like to you squash commits or rebase existing commits from master into your branch before we can merge your pull request. A maintainer will clarify this in the comment thread.
- **question**: Issues can be marked with this label by anybody who would like other contributors or maintainers to answer a specific question before an issue can be closed. These normally do not assume any skill level (although may sometimes require maintainers to have the final say on them) and are great opportunities for all members of our community to steer the direction of the project.
- **refactoring**: If an issue requires code to be refactored before a particular change can be made, or if you spot inelegant patterns or implementations in code that you feel could be better, then feel free to add this label to an issue. If the issue is the latter type, please be careful about the language you use in these threads. For example, things like "this code sucks!" or "you must be an idiot!" are unacceptable!. Programmers have feelings too and there are ways to suggest code changes without insulting people!
- **security**: If you spot an issue related to security issues (e.g. invalid SSL certs, potential CSRF issues), mark it with this label. Don't forget to be a good OSS citizen and always report zero-day issues through a private channel to minimise impact to your fellow users!
- **UX**: These issues relate to how the site works, or more holistically, how the site _feels_ to the end user, and will normally be related to the front-end of the website. These issues might typically relate to confusion stemming from navigation, form elements, input validation, or breaks in user flows.
- **visual design**: This relates to visual elements of the site that could be improved or are broken. This may be as simple as a change to a CSS colour or font size but may stretch all the way to things that do not render as expected on mobile devices. These are usually good issues for people with front-end development experience to tackle.
- **wontfix**: This means that, after considering your issue in full, your issue is outside of the intended scope of the project and is not something we'd like to add to the codebase right now or in the future. These are used sparingly and are intended to be rare, and are never used without reasoned justification.
## Additional info ## Additional info

Просмотреть файл

@ -1,6 +1,6 @@
MIT License MIT License
Copyright (c) 2016 OSS Friday Copyright (c) Open Source Friday contributors
Permission is hereby granted, free of charge, to any person obtaining a copy Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal of this software and associated documentation files (the "Software"), to deal

Просмотреть файл

@ -1,35 +1,24 @@
# OSS Friday # Open Source Friday
Contribute to open source every Friday :beers: Contribute to open source every Friday :beers:
## What is this? ## What is this?
OSS Friday is a movement, inspired by https://24pullrequests.com, to encourage people to contribute to open source every Friday :christmas_tree: Open Source Friday is a movement to encourage companies, people and maintainers to contribute to open source every Friday :christmas_tree:
*Alternative name: 52 pull requests* 🤣 *Alternative name: 52 pull requests* 🤣
Some of the things that worked well for 24 Pull Request that I'd like replicate: Some of the things that worked well for 24 Pull Requests that we'd like replicate:
- **opt-in for maintainers** - only suggesting projects that maintainers have suggested means we don't send a swarm of extra maintainer work to someone who doesn't want it or can't handle it. - **opt-in for maintainers** - only suggesting projects that maintainers have suggested means we don't send a swarm of extra maintainer work to someone who doesn't want it or can't handle it.
- **Wisdom of crowds** - if lots of people are doing the same thing at the same time more people will make an effort to join in - **wisdom of crowds** - if lots of people are doing the same thing at the same time more people will make an effort to join in
- **Gamification** - a little bit of gamification goes a long way, I'm thinking streaks for having done some kind of contribution every Friday throughout the year - **avoid rewards** - Getting free t-shirts or other kinds of gifts tends to bring out bad behaviour like PRs that change a single line of whitespace, which waste maintainers time and energy, the rewards should be a bit less tangible
- **Automation** - many efforts around cultivating open source contributions that require humans tend to fizzle out as the humans involved can't sustain the level of work required to keep it going, 24 Pull Requests pretty much runs itself now which is why it's been so easy to keep it going for 5 years
- **Emails** - sending out regular reminder emails with suggested contribution content works great to give people a kick to keep them going, optional for people who hate email.
- **Avoid rewards** - Getting free t-shirts or other kinds of gifts tends to bring out bad behaviour like prs that change a single line of whitespace, which waste maintainers time and energy, the rewards should be a bit less tangible
Things I'd like to try: Things we'd like to try:
- **Focusing on issues rather than projects** - trying to find a project to contribute to and then find something to do on that project is tricky, instead let's get maintainers to label issues that they want to promote to new contributors with `ossfriday` along with related labels like `Your First PR`, `first-timers-only` and `help wanted` - **not tied to pull requests** - there are lots of ways someone can contribute to an open source project that doesn't require opening a PR on GitHub, we should encourage things like documentation, issue triage, StackOverflow answering, support forum helping, event organising, blogging as well as code contributions
- **not tied to pull requests** - there are lots of ways someone can contribute to an open source project that doesn't require opening a PR on GitHub, we should encourage things like documentation, issue triage, stackoverflow answering, support forum helping, event organising, blogging as well as code contributions - **Three target audiences** - Individual contributors, maintainers and companies are the three types of audience we should be catering to, with documentation for each one on how to get involved.
- **Three target audiences** - Individual contributors, maintainers and companies (h/t @MikeMcQuaid) are the three types of audience we should be catering to, with documentation for each one on how to get involved. I can see the homepage being split in half for contributors and maintainers and then companies slightly further down.
I'm planning on getting something basic together (in ruby of course) before 6th January, the first Friday of 2017 and we can iterate from there 🚀
Would love to hear your ideas, thoughts, feedback, contributions, gifs and emoji reactions, Happy Friday 🍻
Check out the "Hello world" issue to see see the ongoing discussion: https://github.com/ossfriday/ossfriday/issues/2
## Development ## Development
@ -121,4 +110,4 @@ Please note that this project is released with a [Contributor Code of Conduct](C
## Copyright ## Copyright
Copyright (c) 2016 Andrew Nesbitt. See [LICENSE](https://github.com/ossfriday/ossfriday/blob/master/LICENSE.txt) for details. Copyright (c) Open Source Friday contributors. See [LICENSE](https://github.com/ossfriday/ossfriday/blob/master/LICENSE.txt) for details.