|
| 1 | +# Contributing to GrimoireLab Tutorial |
| 2 | + |
| 3 | +This tutorial is built using |
| 4 | +[Markdown syntax](https://guides.github.com/features/mastering-markdown/), |
| 5 | +[Jekyll](https://jekyllrb.com/), and |
| 6 | +[pmarsceill/just-the-docs](https://github.com/pmarsceill/just-the-docs) theme. |
| 7 | + |
| 8 | +All the Markdown files and Jekyll configuration files are maintained in the |
| 9 | +[chaoss/grimoirelab-tutorial](http://github.com/chaoss/grimoirelab-tutorial) |
| 10 | +GitHub repository. |
| 11 | + |
| 12 | +All Contributions are welcome! You can open |
| 13 | +[pull requests](https://github.com/chaoss/grimoirelab-tutorial/pulls) to add |
| 14 | +the related content. Feel free to open |
| 15 | +[issues](https://github.com/chaoss/grimoirelab-tutorial/issues), to report some |
| 16 | +bug, to propose some enhancement, to ask for some new content, or just to comment |
| 17 | +or suggest something. Any feedback is appreciated! |
| 18 | + |
| 19 | +If you are willing to setup the tutorial locally |
| 20 | +```bash |
| 21 | +$ git clone https://github.com/chaoss/grimoirelab-tutorial |
| 22 | +$ cd grimoirelab-tutorial |
| 23 | +$ bundle |
| 24 | +$ bundle exec jekyll serve |
| 25 | +``` |
| 26 | + |
| 27 | +**Note:** Make sure you have git and ruby (version 2.7.x) installed. |
| 28 | + |
| 29 | +This will produce the HTML files, and run an HTTP server that will serve them |
| 30 | +in http://localhost:4000. |
| 31 | + |
| 32 | +## Quick start for contributing |
| 33 | + |
| 34 | +These are the basic steps to set up a developing and testing environment to |
| 35 | +contribute, using GitHub facilities. You can read more details about how to |
| 36 | +contribute to a project in GitHub in |
| 37 | +[How to GitHub: Fork, Branch, Track, Squash and Pull Request](https://gun.io/blog/how-to-github-fork-branch-and-pull-request). |
| 38 | + |
| 39 | +1. Fork the tutorial repository on GitHub. You can use the GitHub web interface |
| 40 | +for this. The result will be a new repository with the rest of your repositories, |
| 41 | +which is a fork (copy) of the GrimoireLab Tutorial. |
| 42 | + |
| 43 | +2. Clone the forked git repository, and create in a local branch for your |
| 44 | +contribution. |
| 45 | + |
| 46 | +``` |
| 47 | +$ git clone https://github.com/username/grimoirelab-tutorial/ |
| 48 | +$ cd grimoirelab-tutorial/ |
| 49 | +$ git checkout -b new-branch-name |
| 50 | +``` |
| 51 | + |
| 52 | +3. In this repository, set up a remote for the upstream (original grimoirelab-tutorial) |
| 53 | +git repository. |
| 54 | + |
| 55 | +``` |
| 56 | +$ git remote add upstream https://github.com/chaoss/grimoirelab-tutorial/ |
| 57 | +``` |
| 58 | + |
| 59 | +4. Now you can change the documentation and then commit it. Except that the |
| 60 | +contribution really needs it, use a single commit, and comment in detail in the |
| 61 | +corresponding commit message what it is intended to do. If it fixes some bug, |
| 62 | +reference it (with the text "_Fixes #23_", for example, for issue number 23). |
| 63 | + |
| 64 | +``` |
| 65 | +$ git add -A |
| 66 | +$ git commit -s |
| 67 | +``` |
| 68 | + |
| 69 | +5. Once your contribution is ready, rebase your local branch with `upstream/master`, |
| 70 | +so that it merges clean with that branch, and push your local branch to a remote |
| 71 | +branch to your GitHub repository. |
| 72 | + |
| 73 | +``` |
| 74 | +$ git fetch upstream |
| 75 | +$ git rebase upstream/master |
| 76 | +$ git push origin new-branch-name |
| 77 | +``` |
| 78 | + |
| 79 | +6. In the GitHub interface, produce a pull request from your branch (you will |
| 80 | +see an option to do that if you visit the webpage for your own repository in |
| 81 | +GitHub). Be sure of including a reasonable comment with the pull request. |
| 82 | + |
| 83 | +7. Visit frequently the pull request in GitHub, to attend to comments and requests |
| 84 | +by GrimoireLab Tutorial developers (or watch it via email). |
| 85 | + |
| 86 | +8. Please keep in mind |
| 87 | +the the pull request will be merged into the codebase only if those comments and |
| 88 | +requests are addressed. |
| 89 | + |
| 90 | +## DCO and Sign-Off for contributions |
| 91 | + |
| 92 | +The [CHAOSS Charter](https://github.com/chaoss/governance/blob/master/project-charter.md) |
| 93 | +requires that contributions are accompanied by a |
| 94 | +[Developer Certificate of Origin](http://developercertificate.org) sign-off. |
| 95 | +For ensuring it, a bot checks all incoming commits. |
| 96 | + |
| 97 | +For users of the git command line interface, a sign-off is accomplished with the |
| 98 | +`-s` as part of the commit command: |
| 99 | + |
| 100 | +``` |
| 101 | +git commit -s -m 'This is a commit message' |
| 102 | +``` |
| 103 | + |
| 104 | +For users of the GitHub interface (using the "edit" button on any file, and producing |
| 105 | +a commit from it), a sign-off is accomplished by writing |
| 106 | + |
| 107 | +``` |
| 108 | +Signed-off-by: Your Name <[email protected]> |
| 109 | +``` |
| 110 | + |
| 111 | +in a single line, into the commit comment field. This can be automated by using a |
| 112 | +browser plugin like [DCO GitHub UI](https://github.com/scottrigby/dco-gh-ui). |
| 113 | + |
| 114 | +## Contributing Guidelines |
| 115 | + |
| 116 | +These are some general guidelines and information related to how we contribute |
| 117 | +to GrimoireLab. You can read about it from the |
| 118 | +[CONTRIBUTING.md](https://github.com/chaoss/grimoirelab/blob/master/CONTRIBUTING.md). |
0 commit comments