Giter VIP home page Giter VIP logo

book-open-source-tips's Introduction

DashboardHub

Open Source Tips

Open Source book on Open Source Tips

Language Status Link
English - https://eddiejaoude.github.io/book-open-source-tips/
Spanish In progress https://eddiejaoude.github.io/book-open-source-tips/index-es.html
Filipino In progress https://eddiejaoude.github.io/book-open-source-tips/index-fil.html

This book contains some common DOs & DON'Ts for Open Source software.

The Open Source community is thriving. Each day the number of Open Source projects grow, as does the army of contributors that maintain them. While this is exciting for the industry, it can be daunting as a developer new to the community. This book aims to provide some tips for newcomers to help them avoid the pitfalls of Open Source development and learn from the community's collective wisdom.

As the ancient proverb goes, Time and tide [and technology] wait for no man. And to the best of our ability, neither will this book. Remember to check the version number for updates!

We would love your help in keeping this book updated. Your comments, suggestions, and pull requests are most welcome.

Open Source is dominating the software industry. Its champions include well-known organisations like Facebook, Twitter and Netflix, but more significantly, an army of passionate individual developers around the world. Their efforts have impacted almost every part of computer science, culminating in millions of open source projects, with billions of lines of code!

While this abundant ecosystem has been of huge benefit to the whole industry, it can also make it difficult for newcomers to know where to start. If you're a newcomer, you might be faced with questions such as "How can I contribute to the Open Source community?" Or, "How do I choose between so many competing projects?" The following DOs and DON'Ts aim to address some of those basic questions, and offer some pointers to aspiring Open Source developers.

Let's dive right in.

All changes in master branch are automatically deployed to the above URL.

Code of Conduct

Dependencies

Quick Start

Install

  • AsciiDoctor (html)
gem install asciidoctor
  • AciiDoctor (pdf)
gem install --pre asciidoctor-pdf
  • Atom preview plugin (optional)
apm install asciidoc-preview
  • VS Code preview plugin (optional)

Launch VS Code Quick Open (Windows: ctrl+p, Mac: cmd+p), paste the following command, and press enter:

ext install joaompinto.asciidoctor-vscode

Source code

Source code is in src/ directory.

Generate html, pdf etc

  • To generate the output in html & pdf:
make

Generated pdf

Generated html

Live Server in Codespace

If you are opening up in GitHub Codespace or VSCode with a DevContainer, then Live Server extension is installed and the port mapping to 5500 setup. Just start liveshare through the command pallet or with 'alt + l then alt + o' then go to remote explorer and open the Live Server in a new browser tab.

book-open-source-tips's People

Contributors

adamantnz avatar akash190104 avatar allanregush avatar brettminnie avatar charlottebrf avatar cnak avatar eddiejaoude avatar eddiejaoude2 avatar elischutze avatar imranvirani avatar jeffslofish avatar jorgepiaggio avatar kalpeshhpatel avatar kobernyk avatar mehulgoel1 avatar mikeshatch avatar mrbbot avatar nathanlschneider avatar notwaving avatar parag456 avatar petehayes102 avatar sam-rowe avatar sarajaoude avatar tanyapowell avatar themarshann avatar umesh-01 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

book-open-source-tips's Issues

Add a section on Licenses

Type Idea
Screenshot included? no
Description When creating an open source project Licensing is just as important as any of the other stuff, I know their are tons of informative sites out there regarding these, but maybe touch on it

Reasons for not doing god commits

Idea
In dont.god-commit.adoc could specific reasons be added to explain why they are bad? I think it would help explain them better.
Screenshot included: no

Filipino Localization/Translation

Good day!

I would like to contribute by translating the documents into the Filipino language so that it will have a broader reach. Can I do it through setting up pull requests?

Thanks!

Beginner open source project list

Please remove items in the right column:

Type Idea
Screenshot included? No
Description It would be awesome if we could include a curated list of open source projects for beginners to have a go at! Also perhaps have a general guide on how to do it such as explaining what issues are and that is usually where you find things that you can work on πŸ˜„

Add more info / example to each tip

Please remove items in the right column:

Type Idea
Screenshot included? no
Description Adding more information to each tip, probably with an example & image

Split book into smaller books / sections

  • Use a visual html page (large buttons) to navigate between the sections (split on DOs / DONTs or something else?)
  • CI to build all books in their own subfolders

test 3

Type Bug / Idea
Screenshot included? yes / no
Description ...

Publish tips checkbox list

High

In no particular order:

Note: creating these as issues on your project and working through them

  • Catchy and easily to follow high level README.md file with simple screenshots / diagrams (include links to more details in the various sections)
  • Have a CONTRIBUTING.md file. Good examples: OpenGov, Atom
  • Include a CODE_OF_CONDUCT.md file. Standard COC
  • Include a LICENSE file. Good resource to help
  • Include an ISSUE_TEMPLATE.md file to help when people create an issue (idea, bug/defect etc)
  • Include a PULL_REQUEST_TEMPLATE.md file to help when people submit a pull request
  • Use milestones in the issue section to organise project journey and priority of issues in that current sprint. Also align milestone name to releases
  • Use labels on issues to highlight: area, size of work with points etc
  • Use releases to show stable versions. Use semver format
  • In the release notes include a changelog
  • Use an existing branching strategy, for example gitflow (even if a cut down version)
  • Split documentation into overview (in README.md) and link to more details. Include explanation of acronyms / abbreviations for people to understand
  • Clean up unused files, branches, releases etc
  • Add badges to the repo for: CI, dependency checkers, lint checkers, deployment etc
  • Documentation to be in the repo, so that it can be kept in sync with the codebase and all changes go via pull request for review (treat documentation like code)
  • Have a simple static website that demonstrates features (could host for free on GitHub Pages)
  • Deploy documentation as part of CI to static website and downloadable PDF (could host for free on GitHub Pages)
  • Use description, link and labels in the project repo (top of landing page)
  • Make the project standards (branching, labelling, testing etc) clear
  • Lock main branch and pull requests require at least 1 review

Medium

In no particular order:

  • Meetup talk
  • Hackathon

General

In no particular order:

  • Make sure issues (stories) are small enough and have enough information for someone outside the team to understand and feel they could contribute - sketches / diagrams etc are usually welcome, these do not have to be pixel perfect
  • Similar to issues, keep pull requests small so others can follow / review - plus improves project's activity
  • Try to respond within 24hrs to a contributor activity on the repo
  • Commit messages must be descriptive but concise
  • Clear project vision
  • Automate as much as possible

Open Source Tips: Translations to Spanish and French

Greetings,

I would like to translate your book Open Source Tips to Spanish and French so it can be more understandable for people limited by the english language. I would like to know how can I commit that translation to your repo.

Thanks in advance for your answer.

Move each to to its own file

Please remove items in the right column:

Type Idea
Screenshot included? no
Description Easier to add to tips & them move then around or group

Spanish translation update

Type Question
Screenshot included? no
Description Hi Eddie... a few days ago a PR #117 was accepted with some files translated to spanish, but I can't see them reflected in the Spanish link. I wanted to take an overview and check if I missed something. Is this an error or am I missing a step? Thanks

test 2

Type Bug / Idea
Screenshot included? yes / no
Description ...

Include more beginner information

Please remove items in the right column:

| Type Idea |
| Screenshot included? | no |
| Description | I think you should include more information about starting with GitHub such as contributing and working with someone. The information already on there contains lots of strange terms that puzzle beginners. |

Diagram of workflow

Type Documentation
Screenshot included? no
Description To help people understand the process: change in master -> TravisCI -> GitHub Pages

test

Type Bug / Idea
Screenshot included? yes / no
Description ...

Open source comapnies

Idea Notes
Screenshot included? no
Description It would be nice if some more information on companies and day to day products which utilise open source software was given

Add the asciidoctor installation steps to Readme

Please remove items in the right column:

Type Idea
Screenshot included? no
Description
  1. Make the project more inclusive for beginners working on open source projects by adding asciidoctor installation steps to Readme: http://asciidoctor.org/
  2. Be clear in the Readme that users only need to do: (a) $ gem update asciidoctor & $ gem install --pre asciidoctor-pdf (if memory is correct) - as I beginner when I first looked at documentation I was unsure of if I needed to go through rest of steps which were only relevant to using ascii for setting up a new project
  3. Include Asciidoc Preview package for Atom: https://atom.io/packages/asciidoc-preview to help beginners check their changes are correct
  4. Include an explanation of what a build file is (for beginners) & how to use it for this project, especially if they don't use the Atom Asciidoc Preview package|

Move GitHub templates to hidden directory

Please remove items in the right column:

Type Idea
Screenshot included? no
Description Clean up root directory by moving GitHub template files to hidden .github directory

Grammatical errors/typo in Readme

  1. The following DOs and DON'Ts aim to address some of those basic questions, and offers some pointers to aspiring Open Source developers.

"and offers", shouldn't that be "and offer"?

  1. Or, "How do I choose between so many competing projects?”.

There shouldn't be a period at the end of this sentence, similar to the sentence just before.

Thanks.

Infographic

Please remove items in the right column:

Type Idea
Screenshot included? no
Description Visual representation of data

bug in content

On page 4:
the subtitle of the codesnippet is doubled
"GitHub syntax highlighingGitHub syntax highlighting"

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.