Open Source First – What we will cover – GitHub
Open Source First
Presentation http://eddiejaoude.github.io/opensource-first-presentation
Source https://github.com/eddiejaoude/opensource-first-presentation
What we will cover
- GitHub overview
- What to look for when using an Open Source Project
- Best Practices for your Open Source Projects
GitHub
How would you describe GitHub?
Interesting to hear other people's thoughts
I would describe GitHub as
Facebook for Developers
Social coding
GitHub is mostly known for OpenSource
"GitHub is how people build software. With a community of more than 14 million people, developers can discover, use, and contribute to over 35 million projects using a powerful collaborative development workflow."
GitHub AboutWho uses?
Why?
Ask the audience
- Extended community & Quality
- Peers - team takes more pride in their work
- More: users / testers / developers
- Who will: log bugs / fix bugs / documentation
- Hiring
- Interoperability - integrate with other systems
- Flexibility of changing to another solution
- ...
Trending
GitHub is not alone
There are alternatives
But is the most popular
GitHub User Account
Follow me & I will follow/chase you
- Slow is smooth and smooth is fast
- Frequent activity is better than all in 1 day
- Organisations/Communities are important
GitHub Organisation
Stars
"Starring a repository allows you to keep track of projects that you find interesting, even if you aren't associated with the project"
- Creating a bookmark for easier access
- Showing appreciation to the repository maintainer for their work
- Dont rely on this alone
Forks
- Use someone’s project as the starting point for your own
- Contribute to someone else’s project
Single Fork
Fork = Upstream
Can have multiple Upstream
GitHub Repository
Not Project
Why not project?
Because a project can have multiple repos (eg. microservices)
Some companies will NOT be able to use it without a license
Why should it be public?
Common responses
- When its ready
- When tests are written
- Project finished
- Perfect / Super high quality
Little secret
- It will NEVER be ready
- Tests should be done first unless a prototype
- It will NEVER be finished
- It will NEVER be perfect if you are continually learning
Why should it be private?
Not valid reasons for Application
- Passwords
- Tokens
- Private keys
README.md is rendered below files
Badges = external services (eg. CI etc)
Great place to put installation instructions / notes to docs or wiki pages
Click colourful bar
Displays languages used
File changes
Branches
Git Flow
- master - production
- dev - mainline
- feature - eg. feature/issue-no-title
- hotfix - eg. hotfix/issue-no-title
GitHub Pages
Free hosting of Static Website
- gh-pages branch - deploy on every commit (CD)
- html, css, javascript, Jekyll template engine
- http://username.github.io or http://organisation.github.io
- http://username.github.io/repository or http://organisation.github.io/repository
Releases / tags
Issue tracking
Labels & Milestones
Pull Requests
Wiki
All know what a wiki is?
Similar to Wikipedia (mediawiki)
Git repo
Markdown
Pulse
Graphs
Markdown
Is your friend
# TEXT h1 ## TEXT h2 *TEXT* Italic **TEXT** Bold `CODE` Inline codeSimple styling for everything - Issues, PRs, Comments Wiki, README...docs
Lots of External tools
- GitHub client
- ZenHub for Issue Tracking
- TravisCI
- ...
Using / Creating an Open Source project
Your project is only as good as its weakest dependency
Who uses composer?
Who looks at their dependencies dependencies?
Please do not just add a dependency and start using it
Don't get bitten - by security, performance, version conflicts
Projects get deleted, die, not supported, even worse bad code could be added
Before you use the Project
Checks & Due Diligence
What would you check?
README
Badges / Description / Documentation / Examples / Demo / Diagrams / Badges / Setup
Badges - CI, code coverage, static code analytics
Prioritise the order of these, like a movie trailer - begin, middle and end
Files
- CONTRIBUTION.md
- LICENSING
- Templates
This gets neglected
Have they thought about accepting improvements
Commit History
Is it frequent
Massive bursts at the beginning is most common
Once a year update dependencies
Regular commits
Just one person
Issues & Pull Requests
- Are these being submitted
- Are these replied to
- Are others replying also
- Are blockers being removed
- Are they closed / merged within a reasonable time
Big online discussions as Issues being the most important
Are these being replied too within 24hours
Just one person or do others support
Are they being closed within 7 days
Are comments being replied too
Automated Tests
- Does the project contain Automated Tests
- Unit / Function / End-to-end
- Continuous Integration (CI)
- Shows a level of quality & risk adverse
Branches
- Is there a branching strategy
- Alarm bells if everything is in master
- Protoype / Spike branches do NOT need tests
- Throw away
- Do NOT merge
Releases
- Dependency: Never use master, dev etc, use stable releases
- Owner: Create releases/tags when you are completely satisified
- Create these from successful builds on CI
De-couple from their code
Design Patterns
Adapter pattern can help
Never change 3rd party code managed by your package manager
Its not yours to change, even if you commit it to your repo
Forking it is an option, but be prepared to merge in upstream changes
Conclusion
Use GitHub
Build a community
Make it easy for anyone to contribute / join
README etc
Contributions
Anyone / anything
- Code & Pull Request
- Any Pull Request - Docs, Typo, etc
- Any feedback / comment
- These are all helpful contributions
Join a community
Ask for help, but be clear & consise
- What is the error
- What did you do to get it / how to reproduce it
- Can you narrow it down to a line(s)
- Screenshot
- What OS
- What Version of the framework/library/tool
- If your work is Open Source, link to the file & line
The community want to help Open Source projects
Research the project first
Resources
- https://guides.github.com
- https://help.github.com
- https://guides.github.com/introduction/flow/