|
1 | | -# Contributing to Angular Rust |
| 1 | +## Contributing to Angular Rust |
2 | 2 |
|
3 | | -Want to contribute to Angular Rust? There are a few things you need to know. |
| 3 | +This describes how developers may contribute to Angular Rust. |
4 | 4 |
|
5 | | -We wrote a **[contribution guide](https://angular-rust.github.io/contributing/how-to-contribute.html)** to help you get started. |
| 5 | +## Mission |
| 6 | + |
| 7 | +Angular Rust's mission is to provide a batteries-included framework for making large scale web and desktop application development as efficient and maintainable as possible. |
| 8 | + |
| 9 | +The design should be configurable and modular so that it can grow with the developer. However, it should provide a wonderful un-boxing experience and default configuration that can woo new developers and make simple web and desktop apps straight forward. The framework should have an opinion about how to do all of the common tasks in web and desktop development to reduce unnecessary cognitive load. |
| 10 | + |
| 11 | +Perhaps most important of all, Angular Rust should be a joy to use. We want to reduce the time spent on tedious boilerplate functionality and increase the time |
| 12 | +available for creating polished solutions for your application's target users. |
| 13 | + |
| 14 | +## How to Contribute |
| 15 | + |
| 16 | +### Join the Community |
| 17 | + |
| 18 | +The first step to improving Angular Rust is to join the community and help grow it! You can find the community on: |
| 19 | + |
| 20 | + [](https://www.facebook.com/groups/angular.rust) |
| 21 | + [](https://stackoverflow.com/questions/tagged/angular-rust) |
| 22 | + [](https://www.youtube.com/channel/UCBJTkSl_JWShuolUy4JksTQ) |
| 23 | + [](https://medium.com/@angular.rust) |
| 24 | + [](https://gitter.im/angular_rust/community) |
| 25 | + |
| 26 | +We believe the wider community can create better code. The first tool for improving the community is to tell the developers about the project by giving it a star. More stars - more members. |
| 27 | + |
| 28 | +  |
| 29 | + |
| 30 | +Once you've joined, there are many ways to contribute to Angular Rust: |
| 31 | + |
| 32 | +* Report bugs (via GitHub) |
| 33 | +* Answer questions of other community members (via Gitter or GitHub Discussions) |
| 34 | +* Give feedback on new feature discussions (via GitHub and Gitter) |
| 35 | +* Propose your own ideas (via Gitter or GitHub) |
| 36 | + |
| 37 | +### How Angular Rust is Developed |
| 38 | + |
| 39 | +We have begun to formalize the development process by adopting pragmatic practices such as: |
| 40 | + |
| 41 | +* Developing on the `develop` branch |
| 42 | +* Merging `develop` branch to `main` branch in 6 week iterations |
| 43 | +* Tagging releases with MAJOR.MINOR syntax (e.g. v0.8) |
| 44 | +** We may also tag MAJOR.MINOR.HOTFIX releases as needed (e.g. v0.8.1) to address urgent bugs. Such releases will not introduce or change functionality |
| 45 | +* Managing bugs, enhancements, features and release milestones via GitHub's Issue Tracker |
| 46 | +* Using feature branches to create pull requests |
| 47 | +* Discussing new features **before** hacking away at it |
| 48 | + |
| 49 | + |
| 50 | +## Dive into code |
| 51 | + |
| 52 | +### Fork this repository |
| 53 | + |
| 54 | +<img align="right" width="360" src="https://dudochkin-victor.github.io/assets/github/fork.png" alt="fork this repository" style="margin-left: 5px;"/> |
| 55 | + |
| 56 | +Fork this repository by clicking on the fork button on the top of this page. |
| 57 | +This will create a copy of this repository in your account. |
| 58 | + |
| 59 | +<br clear="both" /> |
| 60 | + |
| 61 | +### Clone the repository |
| 62 | + |
| 63 | +<img align="right" width="360" src="https://dudochkin-victor.github.io/assets/github/clone.png" alt="clone this repository" style="margin-left: 5px;"/> |
| 64 | + |
| 65 | +Now clone the forked repository to your machine. Go to your GitHub account, open the forked repository, click on the code button and then click the _copy to clipboard_ icon. |
| 66 | + |
| 67 | +Open a terminal and run the following git command: |
| 68 | + |
| 69 | +``` |
| 70 | +git clone "url you just copied" |
| 71 | +``` |
| 72 | + |
| 73 | +where "url you just copied" (without the quotation marks) is the url to this repository (your fork of this project). See the previous steps to obtain the url. |
| 74 | + |
| 75 | +> use SSH tab to copy proper URL |
| 76 | +
|
| 77 | +<img align="right" width="360" src="https://dudochkin-victor.github.io/assets/github/copy-to-clipboard.png" alt="copy URL to clipboard" style="margin-left: 5px;"/> |
| 78 | + |
| 79 | +For example: |
| 80 | + |
| 81 | +``` |
| 82 | +git clone [email protected]:$USER/ruex.git |
| 83 | +``` |
| 84 | + |
| 85 | +where `$USER` is your GitHub username. Here you're copying the contents of the `ruex` repository on GitHub to your computer. |
| 86 | + |
| 87 | + |
| 88 | +<br clear="both" /> |
| 89 | + |
| 90 | +### Create a branch |
| 91 | + |
| 92 | +Change to the repository directory on your computer (if you are not already there): |
| 93 | + |
| 94 | +``` |
| 95 | +cd ruex |
| 96 | +``` |
| 97 | + |
| 98 | +Now create a branch using the `git checkout` command: |
| 99 | + |
| 100 | +``` |
| 101 | +git checkout -b <feature/useful-new-thing> origin/develop |
| 102 | +``` |
| 103 | +replacing `<feature/useful-new-thing>` with the adequate name of the feature you will develop. |
| 104 | + |
| 105 | +### Make necessary changes and commit those changes |
| 106 | + |
| 107 | +Now that you've properly installed and forked Angular Rust, you are ready to start coding (assuming you have a validated your ideas with other community members)! |
| 108 | + |
| 109 | +### Format Your Code |
| 110 | + |
| 111 | +Remember to run `cargo fmt` before committing your changes. |
| 112 | +Many Go developers opt to have their editor run `cargo fmt` automatically when saving Go files. |
| 113 | + |
| 114 | +Additionally, follow the [core Rust style conventions](https://rustc-dev-guide.rust-lang.org/conventions.html) to have your pull requests accepted. |
| 115 | + |
| 116 | +### Write Tests (and Benchmarks for Bonus Points) |
| 117 | + |
| 118 | +Significant new features require tests. Besides unit tests, it is also possible to test a feature by exercising it in one of the sample apps and verifying its |
| 119 | +operation using that app's test suite. This has the added benefit of providing example code for developers to refer to. |
| 120 | + |
| 121 | +Benchmarks are helpful but not required. |
| 122 | + |
| 123 | +### Run the Tests |
| 124 | + |
| 125 | +Typically running the main set of unit tests will be sufficient: |
| 126 | + |
| 127 | +``` |
| 128 | +$ cargo test |
| 129 | +``` |
| 130 | +### Document Your Feature |
| 131 | + |
| 132 | +Due to the wide audience and shared nature of Angular Rust, documentation is an essential addition to your new code. **Pull requests risk not being accepted** until proper documentation is created to detail how to make use of new functionality. |
| 133 | + |
| 134 | +### Add yourself to the list of contributors |
| 135 | + |
| 136 | +Open `CONTRIBUTORS.md` file in a text editor, add your name to it. Don't add it at the beginning or end of the file. Put it anywhere in between. Now, save the file. |
| 137 | + |
| 138 | +<img width="635" src="https://dudochkin-victor.github.io/assets/github/git-status.png" alt="git status" /> |
| 139 | + |
| 140 | +If you go to the project directory and execute the command `git status`, you'll see there are changes. |
| 141 | + |
| 142 | +Add those changes to the branch you just created using the `git add` command: |
| 143 | + |
| 144 | +``` |
| 145 | +git add . |
| 146 | +``` |
| 147 | + |
| 148 | +Now commit those changes using the `git commit` command: |
| 149 | + |
| 150 | +``` |
| 151 | +git commit -m "$COMMENT" |
| 152 | +``` |
| 153 | + |
| 154 | +replacing `$COMMENT` with appropriate description of your changes. |
| 155 | + |
| 156 | +### Push changes to GitHub |
| 157 | + |
| 158 | +Push your changes using the command `git push`: |
| 159 | + |
| 160 | +``` |
| 161 | +git push origin <feature/useful-new-thing> |
| 162 | +``` |
| 163 | + |
| 164 | +replacing `<feature/useful-new-thing>` with the name of the branch you created earlier. |
| 165 | + |
| 166 | +### Submit your changes for review |
| 167 | + |
| 168 | +Once you've done all of the above & pushed your changes to your fork, you can create a pull request for review and acceptance. |
| 169 | + |
| 170 | +If you go to your repository on GitHub, you'll see a `Compare & pull request` button. Click on that button. |
| 171 | + |
| 172 | +<img width="1000" src="https://dudochkin-victor.github.io/assets/github/compare-and-pull.png" alt="create a pull request" /> |
| 173 | + |
| 174 | +Now submit the pull request. |
| 175 | +Do not forget to set develop branch for your pull request. |
| 176 | + |
| 177 | +<img width="1000" src="https://dudochkin-victor.github.io/assets/github/submit-pull-request.png" alt="submit pull request" /> |
| 178 | + |
| 179 | + |
| 180 | +## Where to go from here? |
| 181 | + |
| 182 | +Congrats! You just completed the standard _fork -> clone -> edit -> pull request_ workflow that you'll encounter often as a contributor! |
| 183 | + |
| 184 | +You can check more details in our **[detailed contribution guide](https://angular-rust.github.io/contributing/)**. |
| 185 | + |
| 186 | +You could join our gitter team in case you need any help or have any questions. [Join gitter team](https://gitter.im/angular_rust/community). |
0 commit comments